Slider
The <Slider> is a form component that allows users to quickly select a value within a range. They should be used when the upper and lower bounds of the range are known and static.
Sliders provide a visual indication of adjustable content, where the user can increase or decrease the value by moving the handle along a horizontal track.
Anatomy
Sliders consist of a track element showing the range of available values, one or more thumbs showing the current values, an output displaying the current values textually, and an optional label.
The thumbs can be dragged to allow a user to change their value. In addition, the track can be clicked to move the nearest thumb to that position.
Appearance
The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.
| Property | Type | Description |
|---|---|---|
variant | - | The available variants of this component. |
size | - | The available sizes of this component. |
Usage
A slider is useful when selecting a value or range within a continuous or evenly spaced numeric scale feels more natural through direct manipulation than by entering values manually. It is well suited for inputs where the approximate position on a scale matters more than exact precision, such as setting volume, adjusting brightness, or filtering results within a price or date range. By making the scale visible and interactive, a slider allows users to quickly explore and adjust values while maintaining a clear sense of their relative position.
Ranges
Use the range feature of a slider when users need to select both a minimum and maximum value within the same scale, such as defining a price range, date span, or acceptable measurement limits. This approach works best when the range boundaries are equally important and the relationship between them is immediately clear in a single, continuous control.
When multiple thumbs are rendered, each thumb should have an aria-label, which is provided via the thumbLabels prop.
Scale and Granularity
Choose a scale that aligns with the way users think about the values they are adjusting. Always define a clear starting point and ending point (`), and select step intervals that feel natural within that range.
If the user needs to work with very large value spans or make fine-tuned adjustments, a slider is not the best choice. In those cases, prefer using a different input method such as a number field.
Use a slider for selecting a value with clear, evenly spaced steps.
Use a slider for entering precise values like 8,947.13.
Value formatting
Always format the slider value using an appropriate number format to improve clarity and ensure the displayed information is meaningful. This helps users immediately understand the context of what they are selecting, supports decision-making, and reduces potential confusion.
You can define the format using the formatOptions prop. It supports all options available through Intl.NumberFormat, and will automatically localize the number format based on the user's system settings.
Min and Max Values
Set meaningful and realistic minimum and maximum values that reflect the task the user is trying to complete. These boundaries help users stay within a useful range and avoid invalid input.
By default, the slider values reflect percentages between 0 and 100. A different scale can be used by using the minValue and maxValue props.
Usage in Forms
The name attribute determines how the slider’s value is submitted with the form. For a single-thumb slider, name accepts a string and will submit a single numeric value. For a two-thumb slider, name accepts a string tuple, allowing both the minimum and maximum values to be submitted as separate fields. This ensures that the form captures the full range selection without additional processing.
Props
aria-describedby?string;
aria-details?string;
aria-label?string;
aria-labelledby?string;
className?ClassNameOrFunction<SliderRenderProps>;
defaultValue?number | number[]description?ReactNode;
dir?string;
disabled?boolean;
true, the input is disabled."false"formatOptions?NumberFormatOptions;
hidden?boolean;
id?string;
inert?boolean;
label?ReactNode;
lang?string;
maxValue?number;
100minValue?number;
0name?string | [string, string];
name attribute for the slider input(s), used for form submission.
- For single-thumb sliders, provide a string.
- For range sliders (two thumbs), provide a tuple of two strings, one for each thumb.
onAnimationEnd?AnimationEventHandler<HTMLDivElement>;
onAnimationEndCapture?AnimationEventHandler<HTMLDivElement>;
onAnimationIteration?AnimationEventHandler<HTMLDivElement>;
onAnimationIterationCapture?AnimationEventHandler<HTMLDivElement>;
onAnimationStart?AnimationEventHandler<HTMLDivElement>;
onAnimationStartCapture?AnimationEventHandler<HTMLDivElement>;
onAuxClick?MouseEventHandler<HTMLDivElement>;
onAuxClickCapture?MouseEventHandler<HTMLDivElement>;
onChange?(value: number | number[]) => void;
onChangeEnd?(value: number | number[]) => void;
onClick?MouseEventHandler<HTMLDivElement>;
onClickCapture?MouseEventHandler<HTMLDivElement>;
onContextMenu?MouseEventHandler<HTMLDivElement>;
onContextMenuCapture?MouseEventHandler<HTMLDivElement>;
onDoubleClick?MouseEventHandler<HTMLDivElement>;
onDoubleClickCapture?MouseEventHandler<HTMLDivElement>;
onGotPointerCapture?PointerEventHandler<HTMLDivElement>;
onGotPointerCaptureCapture?PointerEventHandler<HTMLDivElement>;
onLostPointerCapture?PointerEventHandler<HTMLDivElement>;
onLostPointerCaptureCapture?PointerEventHandler<HTMLDivElement>;
onMouseDown?MouseEventHandler<HTMLDivElement>;
onMouseDownCapture?MouseEventHandler<HTMLDivElement>;
onMouseEnter?MouseEventHandler<HTMLDivElement>;
onMouseLeave?MouseEventHandler<HTMLDivElement>;
onMouseMove?MouseEventHandler<HTMLDivElement>;
onMouseMoveCapture?MouseEventHandler<HTMLDivElement>;
onMouseOut?MouseEventHandler<HTMLDivElement>;
onMouseOutCapture?MouseEventHandler<HTMLDivElement>;
onMouseOver?MouseEventHandler<HTMLDivElement>;
onMouseOverCapture?MouseEventHandler<HTMLDivElement>;
onMouseUp?MouseEventHandler<HTMLDivElement>;
onMouseUpCapture?MouseEventHandler<HTMLDivElement>;
onPointerCancel?PointerEventHandler<HTMLDivElement>;
onPointerCancelCapture?PointerEventHandler<HTMLDivElement>;
onPointerDown?PointerEventHandler<HTMLDivElement>;
onPointerDownCapture?PointerEventHandler<HTMLDivElement>;
onPointerEnter?PointerEventHandler<HTMLDivElement>;
onPointerLeave?PointerEventHandler<HTMLDivElement>;
onPointerMove?PointerEventHandler<HTMLDivElement>;
onPointerMoveCapture?PointerEventHandler<HTMLDivElement>;
onPointerOut?PointerEventHandler<HTMLDivElement>;
onPointerOutCapture?PointerEventHandler<HTMLDivElement>;
onPointerOver?PointerEventHandler<HTMLDivElement>;
onPointerOverCapture?PointerEventHandler<HTMLDivElement>;
onPointerUp?PointerEventHandler<HTMLDivElement>;
onPointerUpCapture?PointerEventHandler<HTMLDivElement>;
onScroll?UIEventHandler<HTMLDivElement>;
onScrollCapture?UIEventHandler<HTMLDivElement>;
onTouchCancel?TouchEventHandler<HTMLDivElement>;
onTouchCancelCapture?TouchEventHandler<HTMLDivElement>;
onTouchEnd?TouchEventHandler<HTMLDivElement>;
onTouchEndCapture?TouchEventHandler<HTMLDivElement>;
onTouchMove?TouchEventHandler<HTMLDivElement>;
onTouchMoveCapture?TouchEventHandler<HTMLDivElement>;
onTouchStart?TouchEventHandler<HTMLDivElement>;
onTouchStartCapture?TouchEventHandler<HTMLDivElement>;
onTransitionCancel?TransitionEventHandler<HTMLDivElement>;
onTransitionCancelCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionEnd?TransitionEventHandler<HTMLDivElement>;
onTransitionEndCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionRun?TransitionEventHandler<HTMLDivElement>;
onTransitionRunCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionStart?TransitionEventHandler<HTMLDivElement>;
onTransitionStartCapture?TransitionEventHandler<HTMLDivElement>;
onWheel?WheelEventHandler<HTMLDivElement>;
onWheelCapture?WheelEventHandler<HTMLDivElement>;
ref?Ref<HTMLDivElement>;
ref.current to null
(or call the ref with null if you passed a callback ref).
@see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}slot?string | null;
null value indicates that the local props completely override all props received from a parent.step?number;
1thumbLabels?string | [string, string];
translate?"yes" | "no";
value?number | number[]width?WidthProp;
"full"Alternative components
There are alternative UI elements that can be used in place of sliders, depending on the specific use case and design goals. Some alternatives include:
NumberField: Instead of using a slider, users can directly input the desired value into a numeric input field. This approach provides precise control and is particularly useful when users need to input specific or exact values.
Combobox: Can be used to present a predefined set of options from which users can choose. This can be a suitable alternative when there is a limited range of choices or discrete values to select from.