Slider

Allows to make selections from a range of values.

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.

Note

For accessibility reasons you can use the left and right arrow keys on your keyboard to select a value.

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.

Anatomy of slider

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.

Variant
Size
The selected theme does not has any options for "variant" and "size".
50
PropertyTypeDescription
variant-The available variants of this component.
size-The available sizes of this component.

Usage

Sliders allow users to view and select a value (or range) along a track. They’re ideal for adjusting settings such as volume and brightness.

A slider’s step size defines the increments at which the slider can move, allowing users to make finer or coarser adjustments based on the context — such as adjusting volume in single steps versus increments of ten. Setting an appropriate step size enhances usability, especially for precise inputs. The step default increment is 1.

Label

The label is automatically placed on top of the slider and aligned to its left side. It informs users what value(s) they have selected. You can place it with the label prop.

0
Do

Do label the slider appropriately with the value being modified.

Range slider

The slider can be configured with multiple thumbs to select a range of related values. A common use-case of this component is a price range picker that allows a user to set the minimum and maximum price.

To make it work you need at least to define defaultValues (uncontrolled) or value (controlled) and for accessibility reasons, you should set the thumbLabels prop.

€10.00 – €30.00

Step precision

Selecting a precise value using a slider can be challenging, as it often requires fine motor control, even with a well-designed slider. When attempting to pick a single, specific value, users may find themselves overshooting or undershooting the target.

Task: Try picking a random number on the slider, then attempt to pick the very next number without using the keyboard for assistance. Take note of how many attempts it takes to reach that exact number.

This exercise highlights the difficulty in achieving precise control with sliders, especially at smaller increments. For users, this can become frustrating, particularly in applications where exact values are necessary. This is why well-considered step sizes and alternative input methods (e.g., <NumberField>) are often used alongside sliders to ensure accessibility and ease of use.

0
Don't

Don't use too small number steps. If picking an exact value is important to the goal of the interface, choose an alternate UI element, like NumberField or Combobox.

Value formatting

Values are formatted as a percentage by default, but this can be modified by using the formatOptions prop to specify a different format. formatOptions is compatible with the option parameter of Intl.NumberFormat and is applied based on the current locale.

$60.00

Form

Sliders can also be used in forms. To access the values of multiple thumbs you have to setup the thumbLabels prop. The default label for a single thumb is start.

20 – 30

Additional description

Sometimes the label isn't enough for the user. In this case, to gather additional support for the user we can use the help text. With this we can add helpful hints for the user below the input field. Beside that the help text is placed in close proximity to the associated input field.

80
Defines the search radius

Min and max values

By default, slider values are percentages between 0 and 100. A different scale can be used by setting the minValue and maxValue props.

50

Props

Did you know? You can explore, test, and customize props live in Marigold's storybook. Watch the effects they have in real-time!
aria-describedby?
string;
Identifies the element (or elements) that describes the object.
aria-details?
string;
Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-label?
string;
Defines a string value that labels the current element.
aria-labelledby?
string;
Identifies the element (or elements) that labels the current element.
className?
string | ((values: SliderRenderProps & { defaultClassName: string }) => string);
The CSS className for the element. A function may be provided to compute the class based on component state.
defaultValue?
number | number[]
The default value (uncontrolled).
description?
ReactNode;
A helpful text.
disabled?
boolean;
If true, the input is disabled.
Defaults to:
"false"
formatOptions?
NumberFormatOptions;
The display format of the value label.
id?
string;
The element's unique identifier. See MDN.
label?
string;
Set the label of the slider.
maxValue?
number;
The slider's maximum value.
Defaults to:
100
minValue?
number;
The slider's minimum value.
Defaults to:
0
onChange?
(value: number | number[]) => void;
Handler that is called when the value changes.
onChangeEnd?
(value: number | number[]) => void;
Fired when the slider stops moving, due to being let go.
ref?
Ref<HTMLDivElement>;
Allows getting a ref to the component instance. Once the component unmounts, React will set 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;
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.
step?
number;
The slider's step value.
Defaults to:
1
thumbLabels?
string[]
Labels for the thumbs in the slider. Also used for the name when submitting the form.
value?
number | number[]
The current value (controlled).
width?
WidthProp;
Sets the width of the field. You can see allowed tokens here: https://tailwindcss.com/docs/width
Defaults to:
"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.

Last update: 6 months ago