Slider
A slider picks a level from a short run of steps rather than a typed number, and a description says what the current step means.
Installation
npx shadcn@latest add @flyingsalmon/sliderUsage
import { useState } from 'react'
import { Slider } from '@/components/ui/slider'
export function SliderUsage() {
const [nights, setNights] = useState(3)
return (
<Slider
label="Nights"
min={1}
max={14}
value={nights}
description={`${nights} nights`}
onValueChange={setNights}
/>
)
}Examples
Steps that mean something
The description is your words for the current step. It sits under the track and is what a screen reader announces, so a step reads as its meaning, not its index.
Disabled
Disabled dims the slider, its label, and its description, and takes the thumb out of the tab order. Say why in the description.
In a form
Move the slider and save. The slider is controlled, name posts the value with the form, and the card shows the saved budget.
Guidelines
When to use
- To pick a level from a short run of steps, such as a pace or a budget band.
- When the steps have a meaning you can write in a sentence.
When not to use
- Use Number field when the traveller knows the exact number to enter, such as a budget of $1,200. A slider makes them hunt for it.
- Use Toggle group for a few named options with no order, because a track implies one.
- Use Date picker to pick a date.
Do and don’t
- DoKeep to about seven steps, each a level the traveller could name.A dot marks every step, so a long run turns the track into a dotted line with no meaning.
- DoSay under the track what the current step means, with its consequence: "$150 a day per person for 7 days, before flights".The description is the only place that says where the thumb is, and a figure the traveller can weigh turns a position into a decision.
- Don’tMark the ends of the track with their own figures.End labels make the traveller interpolate. The description already names the step the thumb is on.
- DoOffer an exact entry beside the slider, one ghost button away, when the traveller may already know the figure.The slider answers "roughly". A traveller who knows their number should type it, not hunt for it on a track.
Accessibility
| Key | Description |
|---|---|
| Tab | Moves focus to the thumb. A disabled slider leaves the tab order. |
| ArrowLeftArrowDown | Moves one step down and stops at the minimum. |
| ArrowRightArrowUp | Moves one step up and stops at the maximum. |
| PageDownPageUp | Moves ten steps down or up. |
| Shift+ArrowLeftShift+ArrowRight | Moves ten steps down or up, as do Shift+ArrowDown and Shift+ArrowUp. |
| HomeEnd | Jumps to the minimum or the maximum. |
The thumb is the slider. It takes its name from the label and its aria-valuetext from the description. The dots and the fill are hidden from assistive technology, because the value text already says what they show. The focus ring appears on keyboard focus only. required marks the label; a slider always holds a value, so there is nothing for it to block. The accessibility page covers the rules every component follows.
API
Slider
Slider is controlled: it takes a value and reports the next one. It takes no other props.
| Prop | Type | Default | Description |
|---|---|---|---|
| label | string | Required | The text above the track. |
| value | number | Required | The current step. |
| onValueChange | (value: number) => void | Required | Called with the next value as the thumb moves. |
| min | number | 0 | The lowest value. |
| max | number | 100 | The highest value. |
| step | number | 1 | The distance between steps. A dot marks each one. |
| description | string | – | What the current step means, shown under the track and announced as the value text. |
| required | boolean | false | Marks the label. |
| disabled | boolean | false | Dims the slider and takes the thumb out of the tab order. |
| name | string | – | Posts the value under this name inside a form. |
| id | string | – | The id of the thumb. One is generated when omitted. |
| className | string | – | Styles the wrapper. The slider fills its container up to a fixed maximum width, so use this to narrow it further. |