Slider | Calcite Design System

Sliders are used to set linear values while providing intuitive visual feedback.

Overview

Sliders allow users to view a selected value, or range of information. Sliders provide a visual indicator, or handle of the current value, which is adjustable. This allows the user to increase or decrease the value(s) by moving the Slider's handle along a horizontal track.

Configurable properties support the ability to add ticks, labels with labelTicks, precision handles with precise, and a histogram with hasHistogram.

Sample

Usage

When offering the user a numeric adjustable value or range
Adjusting a buffer area
Opacity or transparency control
Volume control
Adjusting or setting a map extent
A video timeline

Accessibility

Form controls such as Slider should specify their labelText property or be accompanied by a Label component to provide context to assistive technologies. For additional information, refer to the forms and labels accessibility guidance.

Key	Function
`Arrow left`	Reduces the component's `value` by the `step` (default value is `"1"`).
`Arrow right`	Increments the component's `value` by the `step` (default value is `"1"`).
`Arrow down`	Reduces the component's `value` by the `step` (default value is `"1"`).
`Arrow up`	Increments the component's `value` by the `step` (default value is `"1"`).
`Tab`	Moves focus in and out of the component. For range values where `minValue` and `maxValue` are set and the currently focused item is the minimum value, focus will proceed to the maximum value.
`Tab` and `Shift`	Moves focus in and out of the component. For range values where `minValue` and `maxValue` are set and the currently focused item is the maximum value, focus will proceed to the minimum value.

API reference

Properties

Property	Attribute	Description	Type	Default
disabled	disabled	When `true`, interaction is prevented and the component is displayed with lower opacity.	`boolean`	`false`
fillPlacement	fill-placement	When `value` is specified for single values, determines the track's fill relative to the component's handle. When `minValue` and `maxValue` are specified for multiple values, displays the fill between the `minValue` and `maxValue` handles.	`"start" \| "none" \| "end"`	`"start"`
form	form	Specifies the `id` of the component's associated form. When not set, the component is associated with its ancestor form element, if one exists.	`string`
groupSeparator	group-separator	When `true`, number values are displayed with a group separator corresponding to the language and country format.	`boolean`	`false`
hasHistogram	has-histogram	When `true`, indicates a histogram is present.	`boolean`	`false`
histogram		Specifies a list of the histogram's x,y coordinates within the component's `min` and `max`. Displays above the component's track.	`DataSeries`
histogramStops		Specifies a list of single color stops for a histogram, sorted by offset in ascending order.	`ColorStop[]`
labelFormatter		When specified, allows users to customize handle labels.	`(value: number, type: "value" \| "min" \| "max" \| "tick", defaultFormatter: (value: number) => string) => string \| undefined`
labelHandles	label-handles	When `true`, displays numeric value labels on handles.	`boolean`	`false`
labelText	label-text	Specifies the component's label text.	`string`
labelTicks	label-ticks	When `true` and `ticks` is specified, displays label tick marks with their numeric value.	`boolean`	`false`
max	max	The component's maximum selectable value.	`number`	`100`
maxLabel	max-label	When `minValue` and `maxValue` are specified for multiple values, specifies the accessible name for the `maxValue` handle, such as `"Temperature, upper bound"`.	`string`
maxValue	max-value	For multiple values, specifies the component's upper value.	`number`
messageOverrides		Overrides individual strings used by the component.	`Record<string, unknown> \| undefined`
min	min	Specifies the component's minimum selectable value.	`number`	`0`
minLabel	min-label	Specifies the accessible name associated with the `value` handle (for single values) or `minValue` handle (for multiple values). For instance, `"Temperature, lower bound"`.	`string`
minValue	min-value	For multiple values, the component's lower value.	`number`
mirrored	mirrored	When `true`, the component will display values from high to low. Note that this value will be ignored if the slider has an associated histogram.	`boolean`	`false`
name	name	Specifies the name of the component. Required to pass the component's `value` on form submission	`string`
numberingSystem	numbering-system	Specifies the Unicode numeral system used by the component for localization.	`NumberingSystem`
pageStep	page-step	Specifies the interval to move with the `Page up` or `Page down` keys.	`number`
precise	precise	When `true`, sets a finer point for handles.	`boolean`	`false`
required	required	When `true` and the component resides in a form, the component must have a value in order for the form to submit.	`boolean`	`false`
scale	scale	Specifies the component's size.	`Scale`	`"m"`
snap	snap	When `true` and `step` is specified, enables snap selection via a mouse.	`boolean`	`false`
status	status	Specifies the status of the input field, which determines message and icons.	`Status`	`"idle"`
step	step	Specifies the interval to move with the `Arrow up` or `Arrow down` keys.	`number`	`1`
ticks	ticks	Specifies the interval between tick marks on the number line.	`number`
validationIcon	validation-icon	Specifies the validation icon to display under the component.	`IconName \| boolean`
validationMessage	validation-message	Specifies the validation message to display under the component.	`string`
validityread-only		The component's current validation state.	`ValidityState`
value	value	The component's value.	`number \| number[]`

Styles

Name	Description
--calcite-slider-text-color	Specifies the component's text color.
--calcite-slider-track-color	Specifies the component's track color.
--calcite-slider-track-fill-color	Specifies the component's track fill color.
--calcite-slider-handle-fill-color	Specifies the component's handle fill color.
--calcite-slider-handle-extension-color	Specifies the component's handle extension color.
--calcite-slider-accent-color	Specifies the component's accent color.
--calcite-slider-tick-color	Specifies the component's tick color.
--calcite-slider-tick-border-color	Specifies the component's tick border color.
--calcite-slider-tick-selected-color	Specifies the component's tick color when in selected range.
--calcite-slider-graph-color	Specifies the component's graph color.

Events

Name Description Behavior

Name	Description	Behavior
calciteSliderChange	Fires when the component's handle is released. Note: To constantly listen to the drag event, use `calciteSliderInput` instead.	bubblescomposed
calciteSliderInput	Fires on all updates to the component. Note: Fires frequently during drag. To perform expensive operations consider using a debounce or throttle to avoid locking up the main thread.	bubblescomposed

calciteSliderChange

Fires when the component's handle is released.

Note: To constantly listen to the drag event, use calciteSliderInput instead.

bubbles

composed

calciteSliderInput

Fires on all updates to the component.

Note: Fires frequently during drag. To perform expensive operations consider using a debounce or throttle to avoid locking up the main thread.