Skip to content
WunderUI

Slider

Free

Pick one value or a range on a scale by dragging a thumb or pressing the arrow keys.

npx wunderui-cli add slider

Playground

Volume

Installation

bash
npx wunderui-cli add slider

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
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:

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

Volume

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.

Opacity

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.

Opacity

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.

TaborShiftTab
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 .
ShiftArrow
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.

Volume
60
  • data-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.

  • data-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.

  • data-slot="slider-value"Optional

    Shows the current value or range on the right in tabular figures.

  • data-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.

  • data-slot="slider-track"Optional

    The grey bar the thumbs travel on, 6 px thick, horizontal or vertical. Slider already renders it.

  • data-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.

  • data-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.

  • data-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.

  • data-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.

PropTypeDefaultDescription
valueValue—The value of a controlled slider: a number for one thumb, an array of numbers for a range. Pair it with .
defaultValueValue—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.
minnumber0The lowest value on the scale. The default is 0.
maxnumber100The highest value on the scale. The default is 100.
stepnumber1How far a value moves with one arrow key press, and the grid the thumb snaps to while dragging. The default is 1.
largeStepnumber10How far a value moves with Page Up, Page Down or Shift with an arrow key. The default is 10.
minStepsBetweenValuesnumber0For 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.
disabledbooleanfalseDims 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.
centeredboolean | 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.
bubbleboolean | "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.
marksreadonly 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.
invalidboolean—Marks the slider invalid: the fill and the thumb turn red and the thumbs get .
errorReactNode—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 .
thumbClassNamestring—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 .
formatIntl.NumberFormatOptions— options for the number shown in the bubble and in , such as . wins when both are set.
localeIntl.LocalesArgument—The locale for number formatting. The default is , so 1200.5 reads as 1,200.5.
namestring—The name the value is submitted under when the slider is inside a form.
formstring—The id of the form the slider belongs to, when it is not inside that form in the markup.
classNamestring | (state) => string | undefined—Extra classes for the element. A function receives the state and returns the classes.
styleCSSProperties | (state) => CSSProperties | undefined—Inline styles for the element. A function receives the state and returns the styles.
renderReactElement | (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.

PropTypeDefaultDescription
classNamestring | (state) => string | undefined—Extra classes for the label.
styleCSSProperties | (state) => CSSProperties | undefined—Inline styles for the label.
renderReactElement | (props, state) => ReactElement—Replaces the label element with another element or component.

Shows the current value or range on the right in tabular figures.

PropTypeDefaultDescription
childrennull | (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.
classNamestring | (state) => string | undefined—Extra classes for the value.
styleCSSProperties | (state) => CSSProperties | undefined—Inline styles for the value.
renderReactElement | (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.

PropTypeDefaultDescription
classNamestring | (state) => string | undefined—Extra classes for the element. A function receives the state and returns the classes.
styleCSSProperties | (state) => CSSProperties | undefined—Inline styles for the element. A function receives the state and returns the styles.
renderReactElement | (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.

PropTypeDefaultDescription
classNamestring | (state) => string | undefined—Extra classes for the element. A function receives the state and returns the classes.
styleCSSProperties | (state) => CSSProperties | undefined—Inline styles for the element. A function receives the state and returns the styles.
renderReactElement | (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.

PropTypeDefaultDescription
classNamestring | (state) => string | undefined—Extra classes for the element. A function receives the state and returns the classes.
styleCSSProperties | (state) => CSSProperties | undefined—Inline styles for the element. A function receives the state and returns the styles.
renderReactElement | (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.

PropTypeDefaultDescription
indexnumber—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 .
invalidboolean—Puts on the range input inside the thumb.
disabledbooleanfalseDisables this thumb.
aria-valuetextAriaAttributes["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.
inputRefRef<HTMLInputElement>—A ref to the hidden range input inside the thumb, the focusable element.
tabIndexnumber—The position of the thumb in the tab order. The default is 0.
onFocusFocusEventHandler<HTMLInputElement>—Called when the range input inside the thumb gets focus.
onBlurFocusEventHandler<HTMLInputElement>—Called when the range input inside the thumb loses focus.
onKeyDownKeyboardEventHandler<HTMLInputElement>—Called when a key is pressed on the thumb, before the slider handles it.
classNamestring | (state) => string | undefined—Extra classes for the thumb, for example a different fill.
styleCSSProperties | (state) => CSSProperties | undefined—Inline styles for the thumb.
renderReactElement | (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.

PropTypeDefaultDescription
visibleboolean—Shows the bubble. While the slider is dragged it shows regardless.
joinedboolean—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.

PropTypeDefaultDescription
marks requiredreadonly SliderMarkInput[]—The ticks on the scale: a number, or to name one. Label only the ones that need a word.
minnumber0The lowest value of the scale. Give it the same as the slider.
maxnumber100The 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.

PropTypeDefaultDescription
label requiredReactNode—The visible name of the field. It names every thumb (). Without a label, use with an .
valueValue—The value of a controlled slider: a number for one thumb, an array of numbers for a range. Pair it with .
defaultValueValue—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.
minnumber0The lowest value on the scale. The default is 0.
maxnumber100The highest value on the scale. The default is 100.
stepnumber1How far a value moves with one arrow key press, and the grid the thumb snaps to while dragging. The default is 1.
largeStepnumber10How far a value moves with Page Up, Page Down or Shift with an arrow key. The default is 10.
minStepsBetweenValuesnumber0For 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.
disabledbooleanfalseDims the slider to 40 % and takes it out of the tab order and out of pointer input. The value stays readable.
unitstring—The unit after the current value: sits against the number, a word such as gets a space.
showValuebooleantrueShows the current value beside the label. The default is true.
showLimitsboolean—Shows the minimum and the maximum under the track.
showInputboolean—Adds a number field beside a single slider, or two under a range slider, for exact values.
inputLabelstring—The accessible name of the single number field. The default is the label.
inputLabelsreadonly [string, string]—The names of the two range fields. The default is "Minimum" and "Maximum" followed by the label.
inputPrefixstring—Text inside the number field before the number, such as .
inputSuffixstring—Text inside the number field after the number, such as .
helperReactNode—A hint under the field. An replaces it. It describes the thumbs through .
errorReactNode—Error text under the field. It is announced, replaces the helper, describes the thumbs and marks the slider invalid.
invalidboolean—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.
centeredboolean | 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.
bubbleboolean | "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.
marksreadonly 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.
thumbClassNamestring—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 .
formatIntl.NumberFormatOptions— options for the number shown in the bubble and in , such as . wins when both are set.
localeIntl.LocalesArgument—The locale for number formatting. The default is , so 1200.5 reads as 1,200.5.
namestring—The name the value is submitted under when the slider is inside a form.
formstring—The id of the form the slider belongs to, when it is not inside that form in the markup.
classNamestring | (state) => string | undefined—Extra classes for the field, which is a full-width column.
styleCSSProperties | (state) => CSSProperties | undefined—Inline styles for the slider. A function receives the state and returns the styles.
renderReactElement | (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.

PropTypeDefaultDescription
value requirednumber—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 requiredstring—The accessible name of the field. It is shown above the field when is set.
showLabelboolean—Shows the label above the field instead of hiding it visually.
minnumber0The lowest accepted value. A smaller value is set to it when the field is left. The default is 0.
maxnumber100The highest accepted value. A larger value is set to it when the field is left. The default is 100.
stepnumber1The grid a value snaps to when the field is left. The default is 1.
prefixstring—Text inside the field before the number, such as .
suffixstring—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.
invalidboolean—Draws the field in its error style.
disabledboolean—Dims the field and takes it out of reach.
classNamestring—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.

PropTypeDefaultDescription
value requiredreadonly number[]—The current range as two numbers.
onValueChange required(value) => void—Called with when either field gets a valid value.
labelsreadonly [string, string]["Minimum value", "Maximum value"]The names of the two fields. The default is "Minimum value" and "Maximum value".
minnumber—The lowest accepted value. The default is 0.
maxnumber—The highest accepted value. The default is 100.
stepnumber—The grid a value snaps to when a field is left. The default is 1.
prefixstring—Text inside each field before the number, such as .
suffixstring—Text inside each field after the number, such as .
invalidboolean—Draws both fields in their error style.
disabledboolean—Dims both fields and takes them out of reach.
classNamestring—Extra classes for the row of the two fields.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("slider")
Installnpx wunderui-cli add slider

The full library index for assistants is at /llms.txt.