Slider
A value picked by dragging along a line: one thumb for a number, two for a range.
Installation
npx @yolkui/cli add sliderA range
Two values give two thumbs, for a range such as a price. Name each thumb with getAriaLabel ("Minimum price", "Maximum price"); format writes the numbers your way, in SliderValue and on the marks.
Steps and marks
step makes the thumb snap to whole steps. marks draws a tick and its number under the track for each value you list; keep them few, a handful of named stops rather than every step.
Words on the marks
A mark can be { value, label } with your own words, or label: null for a tick alone. Give getAriaValueText the same words, so a screen reader hears "Medium" and not "1".
With a progress bar
A Slider sets a value and a Progress shows one; they share the track and the fill, so side by side they read as a pair. Here the slider is controlled: value and onValueChange.
In a form
Inside a Field, a FieldLabel put inside the Slider names it and shares the line with SliderValue; name submits the value with the form. A disabled slider cannot be reached with Tab, so a tooltip could never be read: put the reason in a FieldDescription. When SliderValue writes a unit ("30 min"), give getAriaValueText the same words. A Field that fails validation rings the thumb in red; FieldError says why.
Minutes of inactivity before you are signed out.
Set by your administrator.
Vertical
orientation="vertical" stands the track up; it fills the height you give it (160px at least). Marks are drawn for a horizontal slider only.
Right to left
Under dir="rtl" the track fills from the right. Wrap the app in Base UI's DirectionProvider with direction="rtl" as well, so the arrow keys follow: ArrowLeft then raises the value. locale writes the digits the page's way.
API
Slider takes the props of Base UI's Slider; SliderLabel and SliderValue take className and the props of their element.
| Prop | Type | What it does |
|---|---|---|
defaultValue · value | number · number[] | On Slider: one value for one thumb, two for a range. value with onValueChange controls it. |
onValueChange · onValueCommitted | (value) => void | On Slider: while the thumb moves, and once when it is let go. |
min · max · step | number | On Slider: the range (0 to 100) and the step (1). Shift with an arrow key moves ten steps (largeStep). |
marks | (number | { value, label })[] | On Slider: ticks with numbers under the track. A number is written with format; label: null draws the tick alone. |
format · locale | Intl.NumberFormatOptions · string | On Slider: how the numbers are written, in SliderValue, the marks and what a screen reader hears. The browser's language by default, written the US way until the page has loaded; a translated site passes its own, so the numbers never change after load. |
aria-label · getAriaLabel | string · (index) => string | On Slider: the thumb's name without a SliderLabel or FieldLabel; getAriaLabel names each thumb of a range. |
getAriaValueText | (formatted, value, index) => string | On Slider: what a screen reader hears for a thumb's value. |
orientation | horizontal · vertical | On Slider: horizontal by default. |
disabled · name | boolean · string | On Slider: a disabled slider cannot be moved or focused; name submits the value with a form. |
SliderLabel | div | The name, linked to every thumb. |
SliderValue | output | The value as text at the end of the label's line, always in sight; "20 – 70" for a range, a function child writes your own. |
Accessibility
Each thumb is a native range input inside, from Base UI: a screen reader hears its name, value, minimum and maximum, and the keys work as on any slider.
- Arrow keys move one step, Shift with an arrow ten, Page Up and Page Down ten, Home and End go to the ends. In a range, each thumb is its own Tab stop.
- SliderLabel or a FieldLabel names every thumb; without one pass aria-label, and getAriaLabel for a range. In development the console warns when a thumb has no name.
- SliderValue is an output linked to the thumbs and does not announce itself while the thumb moves; the value a screen reader hears comes from the thumb. The marks are for the eye only. When a number alone means little, getAriaValueText says it in words.
- The thumb draws the focus outline, and its 20px knob has a 28px area to aim at. In Windows High Contrast the track, the fill and the knob keep their own outlines.
- A disabled slider is a disabled input: it is skipped by Tab and its value is not submitted. Say why next to it, in a FieldDescription.