Slider
FreePick one value or a range on a scale by dragging a thumb or pressing the arrow keys.
npx wunderui-cli add sliderPlayground
Installation
npx wunderui-cli add sliderWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import {
Slider,
SliderBubble,
SliderControl,
SliderField,
SliderIndicator,
SliderInput,
SliderLabel,
SliderMarks,
SliderRangeInputs,
SliderThumb,
SliderTrack,
SliderValue,
} from "@/components/ui/slider"
import type {
SliderBubbleProps,
SliderFieldProps,
SliderHandle,
SliderInputProps,
SliderMark,
SliderMarkInput,
SliderMarksProps,
SliderProps,
SliderRangeInputsProps,
} from "@/components/ui/slider"Then use it:
import { SliderField } from "@/components/ui/slider"
export function Volume() {
return <SliderField label="Volume" unit="%" defaultValue={40} className="w-80" />
}Expected result: You see the label Volume on the left and 40% on the right, above a track filled up to 40 % and a round thumb you can drag or move with arrow keys.
When to use
Use Slider for
- Choosing a value where the rough position matters more than the exact number, such as volume, opacity or zoom
- Choosing a range between two values, such as a price or an amount
- A value on a scale around a middle point, such as a balance from -100 to +100
Use something else for
- Number Field for an exact figure that people type or step with buttons
- Radio Group for a choice between a few named options, such as Day, Week and Month
- Progress for showing how far a task has come, where people cannot change the value
Orientation
A horizontal slider fills the width of its container. A vertical one fills the height, so put it in a column that has a height; the maximum is at the top.
Value display
SliderField shows the value beside the label. Without a label, a bubble above the thumb shows it while the thumb has focus or is dragged, or all the time if you ask.
Focus the thumb or drag it to show the bubble.
Scale
Show the limits under the track, add tick marks for a slider with steps, or add a number input when exact values matter. A range gets two inputs.
States
A helper explains the field. A disabled slider stays readable and says why in its helper, and an invalid one turns red and shows the error text instead of the helper.
Applies to new sessions.
Set by your workspace admin.
Choose at least 10%.
Keyboard interactions
Every thumb is a native range input, so the browser handles focus and arrow keys, and the slider adds larger steps. A range has two tab stops, the lower thumb first.
- TaborShift+Tab
- Moves focus to the next or previous thumb. A disabled slider is skipped.
- ArrowRightorArrowUp
- Raises the value by one .
- ArrowLeftorArrowDown
- Lowers the value by one .
- Shift+Arrow
- Moves the value by , ten steps by default.
- PageUporPageDown
- Raises or lowers the value by .
- HomeorEnd
- Jumps to the minimum or to the maximum. In a range the thumb stops at the other thumb.
Behavior and motion
What the slider does with its value, thumbs, states and motion.
- Controlled or not
- Pass a value and a change handler to control it, or a default value to let it keep its own. A commit handler runs once on release or key press, which is the place to save.
- One thumb or two
- A number gives one thumb that fills from the minimum, and an array of two gives a range where the lower thumb never passes the upper one. A click on the track moves the nearest thumb.
- Centred
- Centred draws the fill from the middle of the scale, or from a number you pass, and marks the zero point with a short line. It works for one thumb only, and a range keeps its normal fill.
- Vertical
- A vertical slider fills the height of its container, with the maximum at the top and the bubble beside the thumb. SliderField draws no error text for it, though the slider is still marked invalid.
- Bubble
- The bubble fades in while the thumb has focus or is dragged, or always if set. Range thumbs closer than 15 % of the scale share one bubble, and screen readers get the value from the value text.
- Marks and limits
- Marks are decorative ticks under the track, and only the step snaps the thumb. Limits show the lowest and highest value under the ends.
- Value text
- A format function sets the text of the value, bubble and screen reader value, so $25 is announced as $25 and not as 25. Without it values use the English number format, such as 1,200.5.
- Disabled
- A disabled slider is drawn at 40 % opacity, is not focusable and ignores the pointer. The value stays readable.
- Invalid
- Invalid or an error turns the fill and thumb red and marks the thumbs invalid. The error text is an alert and describes the thumbs.
- Hover and dragging
- The thumb fills with the page tone on hover and the subtle tone while dragged, and the cursor becomes a grab hand. The thumb follows the pointer directly, without trailing.
- Motion
- The thumb changes its fill with a quick colour transition, and the bubble moves 4 px and fades in and out. Only opacity and transform animate.
- Reduced motion
- With reduced motion the bubble does not move, it fades in place. Nothing else moves, because the thumb follows the pointer.
Anatomy
The figure builds a slider from its parts: the label and value, then the control, track, indicator and thumb. Bubble and marks are options, and the SliderField wrappers are not shown.
- 1data-slot="slider"
Holds the value and draws one thumb per value: a number gives one thumb, an array of two gives a range. It offers several thumb styles, a centred fill, a value bubble, tick marks and an error state.
- 2data-slot="slider-label"Optional
A visible name for the slider, linked to the thumbs, placed with the value in a row inside the Slider. SliderField draws its own label.
- 3data-slot="slider-value"Optional
Shows the current value or range on the right in tabular figures.
- 4data-slot="slider-control"Optional
The area that takes pointer input, a little taller than the track so it is easy to hit. Slider already renders it.
- 5data-slot="slider-track"Optional
The grey bar the thumbs travel on, 6 px thick, horizontal or vertical. Slider already renders it.
- 6data-slot="slider-indicator"Optional
The filled part of the track up to the value, or between the two thumbs of a range. A centred slider fills from its origin.
- 7data-slot="slider-thumb"Optional
The handle people drag or move with arrow keys, Home, End, Page Up and Page Down, and the element screen readers announce. It takes the page tone on hover and the subtle tone while dragging.
- 8data-slot="slider-bubble"Optional
The decorative value bubble above the thumb. It fades in on focus and while dragging, and thumbs close together share one.
- 9data-slot="slider-marks"Optional
Decorative tick marks on the scale. Label only the marks that need a word, never every step.
- data-slot="slider-body"Optional
- data-slot="slider-error"Optional
- data-slot="slider-mark"Optional
- data-slot="slider-mark-label"Optional
- data-slot="slider-grip"
- data-slot="slider-origin"
- data-slot="slider-center-fill"
- data-slot="slider-field"Optional
A slider as a form field: a label that names the thumbs, the current value with its unit, optional limits, number inputs and helper or error text. An error turns the slider red.
- data-slot="slider-input"Optional
A number field that follows the slider, uses the English number format, and clamps and snaps when you leave it.
- data-slot="slider-range-inputs"Optional
Two number fields for a range. The lower value may not pass the upper one.
- data-slot="slider-field-label"
- data-slot="slider-field-value"Optional
- data-slot="slider-field-limits"Optional
Best practices
- Do
Use SliderField for every slider in a form or panel, so the label and current value always sit next to the thumb. Add number inputs when exact values matter.
- Do
Name every slider: SliderField takes a label and a bare Slider takes an aria-label. A range is announced as Budget, minimum and Budget, maximum.
- Do
Set the step to the precision people need and keep the large step at about ten steps. Shift with an arrow key, Page Up and Page Down move by the large step.
- Do
Pass an array such as 20 and 80 as the value for a range. The slider draws one thumb per value.
- Do
Label only the marks that need a word, such as the first, the default and the last. A label on every tick is noise.
- Do
Show an error through the error prop: the fill and thumb turn red and the text is announced. Say what to change, like Choose at least 10%.
- Do
When a slider is disabled, give the reason in the helper text. The value stays readable, and people shouldn't have to guess why they can't change it.
- Don’t
Don't add SliderThumb children for a range. The array decides how many thumbs there are.
- Don’t
Don't rely on colour alone for an error. The red fill comes with the error text and an invalid state for screen readers.
- Don’t
Don't use a vertical slider without a height. It fills its container's height, so a column without one gives the track nothing to stretch to.
- Don’t
Don't use a Slider for a choice between a few named options. Use a Segmented Control or a Radio Group.
API reference
One table per part. Slider and SliderField also take every prop of the Base UI slider they wrap, and the other parts take the props of the element they render.
Holds the value and draws one thumb per value: a number gives one thumb, an array of two gives a range. It offers several thumb styles, a centred fill, a value bubble, tick marks and an error state.
| Prop | Type | Default | Description |
|---|---|---|---|
| value | Value | — | The value of a controlled slider: a number for one thumb, an array of numbers for a range. Pair it with . |
| defaultValue | Value | — | The starting value of an uncontrolled slider: a number for one thumb, an array of two numbers for a range such as . |
| onValueChange | (value, eventDetails) => void | — | Called on every change while the thumb moves, with the new value (a number for one thumb, an array for a range) and the event details. |
| onValueCommitted | (value, eventDetails) => void | — | Called once when a change ends: the pointer is released or a key is pressed. Use it to save instead of saving on every move. |
| min | number | 0 | The lowest value on the scale. The default is 0. |
| max | number | 100 | The highest value on the scale. The default is 100. |
| step | number | 1 | How far a value moves with one arrow key press, and the grid the thumb snaps to while dragging. The default is 1. |
| largeStep | number | 10 | How far a value moves with Page Up, Page Down or Shift with an arrow key. The default is 10. |
| minStepsBetweenValues | number | 0 | For a range, the fewest steps that must stay between two thumbs, so they can never touch. The default is 0. |
| orientation | "horizontal" | "vertical" | "horizontal" | runs across the container and is the default. runs up a column that has a height, with the maximum at the top. |
| disabled | boolean | false | Dims the slider to 40 % and takes it out of the tab order and out of pointer input. The value stays readable. |
| handle | "circle" | "circle-neutral" | "grip-bars" | "grip-dots" | — | The shape of the thumb: is the brand-outlined default, has a grey rim like a plain button, and are a rounded drag item. |
| centered | boolean | number | — | Fills from the middle of the scale instead of the start and marks the zero point. uses the middle of and , a number sets the origin, such as on -50 to 50. A single value only. |
| bubble | boolean | "always" | — | Shows the value in a bubble above the thumb (beside it when vertical) while it has focus or is dragged. keeps it on screen. Close range thumbs share one bubble. |
| formatValue | (value) => string | — | Turns a value into the text shown in the bubble, beside the label and in , such as . The default is the English number format. |
| marks | readonly SliderMarkInput[] | — | Tick marks under the track. A number is a tick, also names it. Label only the ticks that need a word. The marks are decorative. |
| invalid | boolean | — | Marks the slider invalid: the fill and the thumb turn red and the thumbs get . |
| error | ReactNode | — | Error text under the slider. It is announced, linked to every thumb through and marks the slider invalid. For a vertical slider the text is not drawn; use . |
| thumbClassName | string | — | Extra classes for every thumb, for example to change its fill. |
| thumbAlignment | "center" | "edge" | "edge-client-only" | "center" | How the thumb sits at the ends of the track: puts its middle on the end of the track, keeps the whole thumb inside it. The default is . |
| thumbCollisionBehavior | "push" | "swap" | "none" | "push" | What two thumbs do when they meet: moves the other thumb along, lets them trade places, stops the dragged thumb at the other. The default is . |
| format | Intl.NumberFormatOptions | — | options for the number shown in the bubble and in , such as . wins when both are set. |
| locale | Intl.LocalesArgument | — | The locale for number formatting. The default is , so 1200.5 reads as 1,200.5. |
| name | string | — | The name the value is submitted under when the slider is inside a form. |
| form | string | — | The id of the form the slider belongs to, when it is not inside that form in the markup. |
| className | string | (state) => string | undefined | — | Extra classes for the element. A function receives the state and returns the classes. |
| style | CSSProperties | (state) => CSSProperties | undefined | — | Inline styles for the element. A function receives the state and returns the styles. |
| render | ReactElement | (props, state) => ReactElement | — | Replaces the element with another element or component, or composes it with one. It takes an element or a function that returns one. |
A visible name for the slider, linked to the thumbs, placed with the value in a row inside the Slider. SliderField draws its own label.
| Prop | Type | Default | Description |
|---|---|---|---|
| className | string | (state) => string | undefined | — | Extra classes for the label. |
| style | CSSProperties | (state) => CSSProperties | undefined | — | Inline styles for the label. |
| render | ReactElement | (props, state) => ReactElement | — | Replaces the label element with another element or component. |
Shows the current value or range on the right in tabular figures.
| Prop | Type | Default | Description |
|---|---|---|---|
| children | null | (formattedValues, values) => ReactNode | — | A function that receives the formatted values and the raw values and returns what to show, for example . Without it the value is shown as formatted text. |
| className | string | (state) => string | undefined | — | Extra classes for the value. |
| style | CSSProperties | (state) => CSSProperties | undefined | — | Inline styles for the value. |
| render | ReactElement | (props, state) => ReactElement | — | Replaces the value element with another element or component. |
The area that takes pointer input, a little taller than the track so it is easy to hit. Slider already renders it.
| Prop | Type | Default | Description |
|---|---|---|---|
| className | string | (state) => string | undefined | — | Extra classes for the element. A function receives the state and returns the classes. |
| style | CSSProperties | (state) => CSSProperties | undefined | — | Inline styles for the element. A function receives the state and returns the styles. |
| render | ReactElement | (props, state) => ReactElement | — | Replaces the element with another element or component, or composes it with one. It takes an element or a function that returns one. |
The grey bar the thumbs travel on, 6 px thick, horizontal or vertical. Slider already renders it.
| Prop | Type | Default | Description |
|---|---|---|---|
| className | string | (state) => string | undefined | — | Extra classes for the element. A function receives the state and returns the classes. |
| style | CSSProperties | (state) => CSSProperties | undefined | — | Inline styles for the element. A function receives the state and returns the styles. |
| render | ReactElement | (props, state) => ReactElement | — | Replaces the element with another element or component, or composes it with one. It takes an element or a function that returns one. |
The filled part of the track up to the value, or between the two thumbs of a range. A centred slider fills from its origin.
| Prop | Type | Default | Description |
|---|---|---|---|
| className | string | (state) => string | undefined | — | Extra classes for the element. A function receives the state and returns the classes. |
| style | CSSProperties | (state) => CSSProperties | undefined | — | Inline styles for the element. A function receives the state and returns the styles. |
| render | ReactElement | (props, state) => ReactElement | — | Replaces the element with another element or component, or composes it with one. It takes an element or a function that returns one. |
The handle people drag or move with arrow keys, Home, End, Page Up and Page Down, and the element screen readers announce. It takes the page tone on hover and the subtle tone while dragging.
| Prop | Type | Default | Description |
|---|---|---|---|
| index | number | — | The position of the thumb in a range: 0 for the lower one, 1 for the upper one. sets it for you. |
| handle | "circle" | "circle-neutral" | "grip-bars" | "grip-dots" | "circle" | The shape of this thumb. See on . |
| invalid | boolean | — | Puts on the range input inside the thumb. |
| disabled | boolean | false | Disables this thumb. |
| aria-valuetext | AriaAttributes["aria-valuetext"] | — | Text that says what the value means, such as , when the number alone is not enough for a screen reader. |
| getAriaLabel | (index) => string | null | — | Returns the accessible name of the thumb from its index, such as . |
| getAriaValueText | (formattedValue, value, index) => string | null | — | Returns the of the thumb from the formatted value, the raw value and the index. |
| inputRef | Ref<HTMLInputElement> | — | A ref to the hidden range input inside the thumb, the focusable element. |
| tabIndex | number | — | The position of the thumb in the tab order. The default is 0. |
| onFocus | FocusEventHandler<HTMLInputElement> | — | Called when the range input inside the thumb gets focus. |
| onBlur | FocusEventHandler<HTMLInputElement> | — | Called when the range input inside the thumb loses focus. |
| onKeyDown | KeyboardEventHandler<HTMLInputElement> | — | Called when a key is pressed on the thumb, before the slider handles it. |
| className | string | (state) => string | undefined | — | Extra classes for the thumb, for example a different fill. |
| style | CSSProperties | (state) => CSSProperties | undefined | — | Inline styles for the thumb. |
| render | ReactElement | (props, state) => ReactElement | — | Replaces the thumb element with another element or component. |
The decorative value bubble above the thumb. It fades in on focus and while dragging, and thumbs close together share one.
| Prop | Type | Default | Description |
|---|---|---|---|
| visible | boolean | — | Shows the bubble. While the slider is dragged it shows regardless. |
| joined | boolean | — | One bubble for two close range thumbs: place it with ( or in %). |
| orientation | "horizontal" | "vertical" | "horizontal" | puts the bubble above the thumb, beside it. |
Decorative tick marks on the scale. Label only the marks that need a word, never every step.
| Prop | Type | Default | Description |
|---|---|---|---|
| marks required | readonly SliderMarkInput[] | — | The ticks on the scale: a number, or to name one. Label only the ones that need a word. |
| min | number | 0 | The lowest value of the scale. Give it the same as the slider. |
| max | number | 100 | The highest value of the scale. Give it the same as the slider. |
| orientation | "horizontal" | "vertical" | "horizontal" | puts the ticks under the track, beside it. |
A slider as a form field: a label that names the thumbs, the current value with its unit, optional limits, number inputs and helper or error text. An error turns the slider red.
| Prop | Type | Default | Description |
|---|---|---|---|
| label required | ReactNode | — | The visible name of the field. It names every thumb (). Without a label, use with an . |
| value | Value | — | The value of a controlled slider: a number for one thumb, an array of numbers for a range. Pair it with . |
| defaultValue | Value | — | The starting value of an uncontrolled slider: a number for one thumb, an array of two numbers for a range such as . |
| onValueChange | (value, eventDetails) => void | — | Called on every change while the thumb moves, with the new value (a number for one thumb, an array for a range) and the event details. |
| onValueCommitted | (value, eventDetails) => void | — | Called once when a change ends: the pointer is released or a key is pressed. Use it to save instead of saving on every move. |
| min | number | 0 | The lowest value on the scale. The default is 0. |
| max | number | 100 | The highest value on the scale. The default is 100. |
| step | number | 1 | How far a value moves with one arrow key press, and the grid the thumb snaps to while dragging. The default is 1. |
| largeStep | number | 10 | How far a value moves with Page Up, Page Down or Shift with an arrow key. The default is 10. |
| minStepsBetweenValues | number | 0 | For a range, the fewest steps that must stay between two thumbs, so they can never touch. The default is 0. |
| orientation | "horizontal" | "vertical" | "horizontal" | runs across the container and is the default. runs up a column that has a height, with the maximum at the top. |
| disabled | boolean | false | Dims the slider to 40 % and takes it out of the tab order and out of pointer input. The value stays readable. |
| unit | string | — | The unit after the current value: sits against the number, a word such as gets a space. |
| showValue | boolean | true | Shows the current value beside the label. The default is true. |
| showLimits | boolean | — | Shows the minimum and the maximum under the track. |
| showInput | boolean | — | Adds a number field beside a single slider, or two under a range slider, for exact values. |
| inputLabel | string | — | The accessible name of the single number field. The default is the label. |
| inputLabels | readonly [string, string] | — | The names of the two range fields. The default is "Minimum" and "Maximum" followed by the label. |
| inputPrefix | string | — | Text inside the number field before the number, such as . |
| inputSuffix | string | — | Text inside the number field after the number, such as . |
| helper | ReactNode | — | A hint under the field. An replaces it. It describes the thumbs through . |
| error | ReactNode | — | Error text under the field. It is announced, replaces the helper, describes the thumbs and marks the slider invalid. |
| invalid | boolean | — | Marks the slider invalid without error text: the fill and the thumb turn red and the thumbs get . |
| handle | "circle" | "circle-neutral" | "grip-bars" | "grip-dots" | — | The shape of the thumb: is the brand-outlined default, has a grey rim like a plain button, and are a rounded drag item. |
| centered | boolean | number | — | Fills from the middle of the scale instead of the start and marks the zero point. uses the middle of and , a number sets the origin, such as on -50 to 50. A single value only. |
| bubble | boolean | "always" | — | Shows the value in a bubble above the thumb (beside it when vertical) while it has focus or is dragged. keeps it on screen. Close range thumbs share one bubble. |
| formatValue | (value) => string | — | Turns a value into the text shown in the bubble, beside the label and in , such as . The default is the English number format. |
| marks | readonly SliderMarkInput[] | — | Tick marks under the track. A number is a tick, also names it. Label only the ticks that need a word. The marks are decorative. |
| thumbClassName | string | — | Extra classes for every thumb, for example to change its fill. |
| thumbAlignment | "center" | "edge" | "edge-client-only" | "center" | How the thumb sits at the ends of the track: puts its middle on the end of the track, keeps the whole thumb inside it. The default is . |
| thumbCollisionBehavior | "push" | "swap" | "none" | "push" | What two thumbs do when they meet: moves the other thumb along, lets them trade places, stops the dragged thumb at the other. The default is . |
| format | Intl.NumberFormatOptions | — | options for the number shown in the bubble and in , such as . wins when both are set. |
| locale | Intl.LocalesArgument | — | The locale for number formatting. The default is , so 1200.5 reads as 1,200.5. |
| name | string | — | The name the value is submitted under when the slider is inside a form. |
| form | string | — | The id of the form the slider belongs to, when it is not inside that form in the markup. |
| className | string | (state) => string | undefined | — | Extra classes for the field, which is a full-width column. |
| style | CSSProperties | (state) => CSSProperties | undefined | — | Inline styles for the slider. A function receives the state and returns the styles. |
| render | ReactElement | (props, state) => ReactElement | — | Replaces the slider element with another element or component. It takes an element or a function that returns one. |
A number field that follows the slider, uses the English number format, and clamps and snaps when you leave it.
| Prop | Type | Default | Description |
|---|---|---|---|
| value required | number | — | The current value of the slider. |
| onValueChange required | (value) => void | — | Called with a valid value that is in range, as it is typed and again when the field is left. |
| label required | string | — | The accessible name of the field. It is shown above the field when is set. |
| showLabel | boolean | — | Shows the label above the field instead of hiding it visually. |
| min | number | 0 | The lowest accepted value. A smaller value is set to it when the field is left. The default is 0. |
| max | number | 100 | The highest accepted value. A larger value is set to it when the field is left. The default is 100. |
| step | number | 1 | The grid a value snaps to when the field is left. The default is 1. |
| prefix | string | — | Text inside the field before the number, such as . |
| suffix | string | — | Text inside the field after the number, such as . |
| validate | (value) => string | null | — | An extra rule checked before a value is accepted. Return the error text, or null. |
| invalid | boolean | — | Draws the field in its error style. |
| disabled | boolean | — | Dims the field and takes it out of reach. |
| className | string | — | Extra classes for the wrapper of the label and the field. |
Two number fields for a range. The lower value may not pass the upper one.
| Prop | Type | Default | Description |
|---|---|---|---|
| value required | readonly number[] | — | The current range as two numbers. |
| onValueChange required | (value) => void | — | Called with when either field gets a valid value. |
| labels | readonly [string, string] | ["Minimum value", "Maximum value"] | The names of the two fields. The default is "Minimum value" and "Maximum value". |
| min | number | — | The lowest accepted value. The default is 0. |
| max | number | — | The highest accepted value. The default is 100. |
| step | number | — | The grid a value snaps to when a field is left. The default is 1. |
| prefix | string | — | Text inside each field before the number, such as . |
| suffix | string | — | Text inside each field after the number, such as . |
| invalid | boolean | — | Draws both fields in their error style. |
| disabled | boolean | — | Dims both fields and takes them out of reach. |
| className | string | — | Extra classes for the row of the two fields. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("slider")npx wunderui-cli add sliderThe full library index for assistants is at /llms.txt.