Slider
Material 3 single-value and range sliders with audited size families, accessible thumbs, and explicit web adaptations.
Sliders let users choose a numeric value from a bounded range. Slider selects one value; RangeSlider selects a start/end pair with independently accessible thumbs.
import { RangeSlider, Slider } from '@m3-ui/ui';
<Slider defaultValue={40} label="Volume" />
<RangeSlider
defaultValue={[25, 75]}
label="Price range"
thumbLabels={['Minimum price', 'Maximum price']}
/>When to use
Use a slider when users benefit from choosing approximately or continuously within a meaningful range. Prefer a text/numeric field when exact entry matters more than spatial adjustment, and avoid sliders for choices with no meaningful ordered continuum.
Values and steps
The public slider contract exposes minValue, maxValue, step, orientation, controlled/uncontrolled values, and change events. RangeSlider uses a readonly two-number tuple while adapting to the underlying multi-thumb web state internally.
Keep application validation/formatting separate from the component's numeric state. Use getValueLabel when displayed value text needs formatting.
Sizes
The audited public size family is xSmall, small, medium, large, and xLarge. Choose the semantic size from the surrounding Material hierarchy instead of reproducing handle/track dimensions in CSS.
Range sliders and thumb labels
A range slider has two independent accessible thumbs. When the shared label does not sufficiently identify each thumb, use thumbLabels.
<RangeSlider
aria-label="Temperature range"
defaultValue={[18, 24]}
thumbLabels={['Minimum temperature', 'Maximum temperature']}
/>Behavior and states
React Aria owns slider/thumb roles, keyboard adjustment, pointer dragging, orientation, focus, and value semantics. Material tokens own track, handle, state layers, color, geometry, and visual motion.
Do not implement a second drag/keyboard state machine around the component.
Ticks and value indicators
showTicks and showValueIndicator are explicit audited Material Web adaptations in m3-ui. They are not silently described as Compose-only API or as new normative Material geometry.
<Slider
defaultValue={60}
label="Stepped value"
minValue={0}
maxValue={100}
step={20}
showTicks
showValueIndicator
/>Ticks derive from the configured range and step. The value indicator is visual and does not replace the accessible numeric value exposed by the slider thumb.
Accessibility
Every slider needs an accessible label. Range sliders need enough naming to distinguish the start/end thumbs. Preserve meaningful value text when raw numbers alone are ambiguous, and do not hide the component's keyboard adjustment behavior behind pointer-only interactions.
API reference
Slider
Slider({ label, size, showTicks, showValueIndicator, thumbLabels, getValueLabel, className, style, minValue, maxValue, step, ...props }: SliderProps): JSX.ElementProps
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
getValueLabel | ((value: number, index: number) => ReactNode) | undefined | — | Optional visual formatter for the value indicator. | @m3-ui/ui |
label | ReactNode | — | Visible label. Supply aria-label/aria-labelledby instead for control-only use. | @m3-ui/ui |
showTicks | boolean | undefined | — | Material Web adaptation: render discrete tick marks for the configured step. | @m3-ui/ui |
showValueIndicator | boolean | undefined | — | Material Web adaptation: show a value indicator while a thumb is active. | @m3-ui/ui |
size | SliderSize | undefined | 'xSmall' | Current Material 3 size family. xSmall is the Compose baseline geometry. | @m3-ui/ui |
thumbLabels | readonly string[] | undefined | — | Per-thumb accessible labels; required for a range when the root label is not a string. | @m3-ui/ui |
Inherited React / web props (88)
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
aria-describedby | string | undefined | — | Identifies the element (or elements) that describes the object. | @react-types/shared |
aria-details | string | undefined | — | Identifies the element (or elements) that provide a detailed, extended description for the object. | @react-types/shared |
aria-label | string | undefined | — | Defines a string value that labels the current element. | @react-types/shared |
aria-labelledby | string | undefined | — | Identifies the element (or elements) that labels the current element. | @react-types/shared |
className | ClassNameOrFunction<SliderRenderProps> | undefined | 'react-aria-Slider' | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. | react-aria-components |
defaultValue | number | undefined | — | The default value (uncontrolled). | @react-types/shared |
dir | string | undefined | — | — | @react-types/shared |
formatOptions | Intl.NumberFormatOptions | undefined | — | The display format of the value label. | react-aria-components |
hidden | boolean | undefined | — | — | @react-types/shared |
id | string | undefined | — | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | @react-types/shared |
inert | boolean | undefined | — | — | @react-types/shared |
isDisabled | boolean | undefined | — | Whether the whole Slider is disabled. | react-stately |
lang | string | undefined | — | — | @react-types/shared |
maxValue | number | undefined | 100 | The slider's maximum value. | react-stately |
minValue | number | undefined | 0 | The slider's minimum value. | react-stately |
onAnimationEnd | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationEndCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationIteration | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationIterationCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationStart | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationStartCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAuxClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAuxClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onChange | ((value: number) => void) | undefined | — | Handler that is called when the value changes. | @react-types/shared |
onChangeEnd | ((value: number) => void) | undefined | — | Fired when the slider stops moving, due to being let go. | react-stately |
onClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onContextMenu | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onContextMenuCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onDoubleClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onDoubleClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onGotPointerCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onGotPointerCaptureCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onLostPointerCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onLostPointerCaptureCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseDown | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseDownCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseEnter | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseLeave | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseMove | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseMoveCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOut | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOutCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOver | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOverCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseUp | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseUpCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerCancel | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerCancelCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerDown | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerDownCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerEnter | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerLeave | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerMove | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerMoveCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOut | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOutCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOver | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOverCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerUp | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerUpCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onScroll | UIEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onScrollCapture | UIEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchCancel | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchCancelCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchEnd | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchEndCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchMove | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchMoveCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchStart | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchStartCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionCancel | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionCancelCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionEnd | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionEndCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionRun | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionRunCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionStart | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionStartCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onWheel | WheelEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onWheelCapture | WheelEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
orientation | Orientation | undefined | 'horizontal' | The orientation of the Slider. | react-stately |
render | DOMRenderFunction<"div", SliderRenderProps> | undefined | — | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. | react-aria-components |
slot | string | null | undefined | — | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. | react-aria-components |
step | number | undefined | 1 | The slider's step value. | react-stately |
style | StyleOrFunction<SliderRenderProps> | undefined | — | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. | react-aria-components |
translate | "yes" | "no" | undefined | — | — | @react-types/shared |
value | number | undefined | — | The current value (controlled). | @react-types/shared |
Source: packages/ui/src/components/Slider/Slider.tsx:267
Material fidelity and adaptations
- Family
- Sliders
- Provenance
- spec: Material 3 overview · web: Browser and React Aria semantics · adaptation: m3-ui web adaptation
- Compose mapping
- Slider · RangeSlider
- Visual fidelity
- partial: Legacy visual fidelity has not received an explicit reviewed disposition. Current implementation evidence: Implements single-value and range Material sliders, the audited size family, active/inactive track segments, stop indicator, accessible per-thumb labels, orientation, and stepped values.
- Behavior fidelity
- adapted: React Aria owns slider and thumb semantics, keyboard input, pointer dragging, value state, orientation, and accessible labels. `showTicks` and `showValueIndicator` are intentional Material Web adaptations layered onto the audited Material geometry.
- Semantics fidelity
- adapted: React Aria owns slider and thumb semantics, keyboard input, pointer dragging, value state, orientation, and accessible labels. `showTicks` and `showValueIndicator` are intentional Material Web adaptations layered onto the audited Material geometry.
- Adaptations
- React Aria owns slider and thumb semantics, keyboard input, pointer dragging, value state, orientation, and accessible labels. `showTicks` and `showValueIndicator` are intentional Material Web adaptations layered onto the audited Material geometry.
Material supplies the slider selection model and visual contract. React Aria supplies accessible slider/thumb semantics and browser interaction. Ticks/value indicators remain explicitly classified as audited Material Web adaptations where applicable.
Related components
- Text field — exact typed values.
- Segmented buttons — discrete categorical selection.
- Forms and validation — application form ownership.