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 label, precision handles with precise, and a histogram with has.
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
Sample
Accessibility
Slider should be accompanied by a Label, which provides context of the intent to support assistive technologies.
Keyboard navigation
| 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 min and max 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 min and max 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 | |
| validity | The component's current validation state. | MutableValidityState | ||
| 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 |
|---|---|---|
| calciteSliderChange | Fires when the component's handle is released.
Note: To constantly listen to the drag event,
use calciteSliderInput instead. | |
| 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. |
Methods
| Name | Description | Signature |
|---|---|---|
| componentOnReady | Create a promise that resolves once component is fully loaded. | componentOnReady(): Promise<this> |
| setFocus | Sets focus on the component. | setFocus(options?: FocusOptions): Promise<void> |