Slider

Sliders allow users to make selections from a range of values.

Overview

Sliders reflect a range of values along a bar, from which users may select a single value or a range. They are ideal for adjusting settings such as volume, brightness, or applying image filters.

Sliders can be somewhat difficult to manipulate, so they should be used when an approximate value is good enough. When using sliders, consider the unit. If only whole numbers can be chosen, for example, default the slider to use whole values only.

Usage

forge-slider selects a value — or, with range, a start and end value — along a bounded track through min, max, step, tickmarks, and labeled, and participates in form submission via name. Reserve it for a value that’s fine to be approximate; when a user needs to enter a known, specific number, use a text field instead.

Rules

Use a slider when an approximate value is good enough and dragging gives immediate feedback, like volume or a filter range.

Keep the current value's label visible so users aren't guessing where the handle sits.

Live-update any dependent results as the handle drags, not just after it's released.

Offer a text field alternative alongside a slider when a user might want to enter an exact value.

Don't

Don't use a slider for a binary on/off setting — use a switch instead.

Don't use a slider when a user needs to enter a known, specific value — use a text field instead.

Don't hide the current value's label unless space is truly constrained.

Don't use a slider when the range is very large making it difficult to select specific values accurately.

Range

Set range to render two handles — valueStart and valueEnd — instead of one, for selecting a span rather than a single point.

Two handles select a start and end value instead of a single point.

<forge-slider range data-aria-label-start="Start" data-aria-label-end="End">
</forge-slider>

Tickmarks

Set tickmarks to show marks spaced by step, giving the handle discrete stops to snap to.

Tickmarks spaced by step give the handle discrete stops to snap to.

<forge-slider tickmarks step="10" data-aria-label="Value">
</forge-slider>

Disabled and readonly

disabled excludes the slider from the form; readonly keeps it in the form but locks its value.

Disabled excludes the slider from the form; readonly keeps it in the form but locks its value.

<forge-slider disabled value="30" data-aria-label="Disabled">
</forge-slider>
<forge-slider readonly value="70" data-aria-label="Readonly">
</forge-slider>

Custom labels

Set labelBuilder (or label/labelStart/labelEnd) to caption the handle with something other than a bare number.

A custom label captions the handle instead of a bare number.

<forge-slider value="50" label="50%" data-aria-label="Opacity">
</forge-slider>

Sliders allow users to make selections from a range of values. You can use sliders for selecting values from either a continuous or discrete range, and they can also be used for selecting a single value or a range of values.

import "@tylertech/forge/slider";

Properties

Property	Attribute	Type	Default	Description
`name`	`name`	`string`	—	Controls the form control name.
`nameStart`	`name-start`	`string`	—	Controls the form control name for the start handle in range mode.
`nameEnd`	`name-end`	`string`	—	Controls the form control name for the end handle in range mode.
`value`	`value`	`number`	`50`	Sets the current value of the slider.
`valueStart`	`value-start`	`number`	`33`	Sets the current start value of the slider in range mode.
`valueEnd`	`value-end`	`number`	`67`	Sets the current end value of the slider in range mode.
`label`	`label`	`string`	—	Sets the label text for the slider handle.
`labelStart`	`label-start`	`string`	—	Sets the label text for the start slider handle in range mode.
`labelEnd`	`label-end`	`string`	—	Sets the label text for the end slider handle in range mode.
`labelBuilder`	—	`SliderLabelBuilder`	—	A function that returns a label for the slider handle.
`min`	`min`	`number`	`0`	Sets the minimum value of the slider.
`max`	`max`	`number`	`100`	Sets the maximum value of the slider.
`step`	`step`	`number`	`1`	Sets the step value of the slider.
`tickmarks`	`tickmarks`	`boolean`	`false`	Controls if tickmarks are visible.
`labeled`	`labeled`	`boolean`	`true`	Controls if labels are visible.
`range`	`range`	`boolean`	`false`	Controls range mode.
`disabled`	`disabled`	`boolean`	`false`	Controls if the slider is disabled.
`readonly`	`readonly`	`boolean`	`false`	Controls if the slider is readonly.
—	`data-aria-label`	`string`	—	Sets the `aria-label` attribute on the slider handle.
—	`data-aria-label-start`	`string`	—	Sets the `aria-label` attribute on the start handle in range mode.
—	`data-aria-label-end`	`string`	—	Sets the `aria-label` attribute on the end handle in range mode.

Events

Name	Type	Description
`forge-slider-input`	`CustomEvent<ISliderChangeEventData>`	Dispatches when the slider value changes.
`forge-slider-change`	`CustomEvent<ISliderChangeEventData>`	Dispatches when the slider value changes and the value has been committed.
`forge-slider-range-input`	`CustomEvent<ISliderRangeChangeEventData>`	Dispatches when the slider range values change.
`forge-slider-range-change`	`CustomEvent<ISliderRangeChangeEventData>`	Dispatches when the slider range values change and the values have been committed.

CSS Parts

Name	Description
`::part(slider)`	Styles the slider container element.
`::part(track)`	Styles the track element.
`::part(handle-end)`	Styles the end handle element.
`::part(handle-end-thumb)`	Styles the end handle thumb element.
`::part(handle-end-label)`	Styles the end handle label element.
`::part(handle-end-label-content)`	Styles the end handle label content element.
`::part(handle-start)`	Styles the start handle element.
`::part(handle-start-thumb)`	Styles the start handle thumb element.
`::part(handle-start-label)`	Styles the start handle label element.
`::part(handle-start-label-content)`	Styles the start handle label content element.

CSS Custom Properties

Name	Description
`--forge-theme-primary`	The primary color of the slider.
`--forge-theme-on-primary`	The color of elements placed on top of the primary color (the label text for example).
`--forge-slider-track-height`	The height of the track.
`--forge-slider-active-track-color`	The color of the active track.
`--forge-slider-active-track-height`	The height of the active track.
`--forge-slider-active-track-shape`	The shape of the active track.
`--forge-slider-disabled-active-track-color`	The color of the active track when disabled.
`--forge-slider-disabled-active-track-opacity`	The opacity of the active track when disabled.
`--forge-slider-disabled-handle-color`	The color of the slider handle when disabled.
`--forge-slider-disabled-inactive-track-color`	The color of the inactive track when disabled.
`--forge-slider-disabled-inactive-track-opacity`	The opacity of the inactive track when disabled.
`--forge-slider-focus-handle-color`	The color of the slider handle when focused.
`--forge-slider-handle-color`	The color of the slider handle.
`--forge-slider-handle-height`	The height of the slider handle.
`--forge-slider-handle-width`	The width of the slider handle.
`--forge-slider-handle-shape`	The shape of the slider handle.
`--forge-slider-hover-handle-color`	The color of the slider handle when hovered.
`--forge-slider-inactive-track-color`	The color of the inactive track.
`--forge-slider-inactive-track-height`	The height of the inactive track.
`--forge-slider-inactive-track-shape`	The shape of the inactive track.
`--forge-slider-label-container-shape`	The shape of the label container.
`--forge-slider-label-container-color`	The color of the label container.
`--forge-slider-label-container-height`	The height of the label container.
`--forge-slider-label-text-color`	The color of the label text.
`--forge-slider-pressed-handle-color`	The color of the slider handle when pressed.
`--forge-slider-state-layer-size`	The size of the state layer.
`--forge-slider-with-overlap-handle-outline-color`	The color of the slider handle outline when overlapping.
`--forge-slider-with-overlap-handle-outline-width`	The width of the slider handle outline when overlapping.
`--forge-slider-with-tick-marks-active-container-color`	The color of the active tick mark container when tick marks are visible.
`--forge-slider-with-tick-marks-container-size`	The size of the tick mark container when tick marks are visible.
`--forge-slider-with-tick-marks-disabled-active-container-color`	The color of the active tick mark container when tick marks are visible and disabled.
`--forge-slider-with-tick-marks-disabled-inactive-container-color`	The color of the inactive tick mark container when tick marks are visible and disabled.
`--forge-slider-with-tick-marks-inactive-container-color`	The color of the inactive tick mark container when tick marks are visible.

Keyboard interaction

Ensure every slider control is reachable by the tab key and can be adjusted with the left and right arrow keys — for a range slider, that applies to each thumb independently.