Slider

A value picked by dragging along a line: one thumb for a number, two for a range.

Volume
40

Installation

npx @yolkui/cli add slider

A 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.

Price
$20 – $70

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.

Opacity
50

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".

Text size
Medium

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.

Simulated upload
30
Uploading report.pdf
x

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.

30 min

Minutes of inactivity before you are signed out.

every 6 h

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.

PropTypeWhat it does
defaultValue · valuenumber · number[]On Slider: one value for one thumb, two for a range. value with onValueChange controls it.
onValueChange · onValueCommitted(value) => voidOn Slider: while the thumb moves, and once when it is let go.
min · max · stepnumberOn 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 · localeIntl.NumberFormatOptions · stringOn 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 · getAriaLabelstring · (index) => stringOn Slider: the thumb's name without a SliderLabel or FieldLabel; getAriaLabel names each thumb of a range.
getAriaValueText(formatted, value, index) => stringOn Slider: what a screen reader hears for a thumb's value.
orientationhorizontal · verticalOn Slider: horizontal by default.
disabled · nameboolean · stringOn Slider: a disabled slider cannot be moved or focused; name submits the value with a form.
SliderLabeldivThe name, linked to every thumb.
SliderValueoutputThe 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.