1. Components
  2. Inputs
  3. Slider

Slider

An input where the user selects a value from within a given range.

Aria docsAria API ReferenceReport an issueEdit this page
<Slider defaultValue={50} />

Installation

npx dotui-cli@latest add slider

Options

Size

Use the size prop to control the size of the slider. The default variant is "md".

<Slider size="sm" />
<Slider size="md" />
<Slider size="lg" />

Orientation

Sliders are horizontally oriented by default. The orientation prop can be set to "vertical" to create a vertical slider.

<Slider orientation="vertical" />

Label

A visual label can be provided using the label prop or a hidden label using aria-label prop.

<Slider label="Opacity" defaultValue={50} />
<Slider aria-label="Opacity" defaultValue={50} />

Description

A description can be supplied to the slider using the description prop.

Adjust the background opacity.
<Slider label="Opacity" description="Adjust the background opacity." />

Value label

The valueLabel boolean prop can be used to display the current value of the slider. The valueLabel prop can also be set to a function that returns a custom value label.

50
50 of 100 Donuts
<Slider label="Donuts to buy" valueLabel />
<Slider
  label="Donuts to buy"
  valueLabel={(donuts) => `${donuts[0]} of 100 Donuts`}
/>

Value scale

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

25
<Slider label="Cookies to buy" minValue={1} maxValue={50} />

Step

The step prop can be used to snap the value to certain increments.

0
<Slider label="Opacity" step={5} />

Format options

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
<Slider label="Price" formatOptions={{ style: "currency", currency: "JPY" }} />

Range

Passing an array to the defaultValue or value props will create a range slider.

200 - 300
<Slider defaultValue={[200, 300]} />

Disabled

Use the isDisabled prop to disable the slider.

<Slider isDisabled />

Composition

If you need to customize things further, you can drop down to the composition level.

50
Adjust the volume.
<SliderRoot>
  <div>
    <Label>Volume</Label>
    <SliderValueLabel />
  </div>
  <SliderControls />
</SliderRoot>
50
Adjust the volume.
<SliderRoot>
  <Label>Volume</Label>
  <SliderValueLabel />
  <div>
    <Volume1Icon />
    <SliderTrack>
      <SliderFiller />
      <SliderThumb />
    </SliderTrack>
    <Volume2Icon />
  </div>
</SliderRoot>

Uncontrolled

The defaultValue prop can be used to set the default state.

<Slider defaultValue={20} />

Controlled

Use the value and onChange props to control the value of the input.

Value: 50
const [value, setValue] = React.useState(50);
return <Slider value={value} onChange={(value) => setValue(value as number)} />;

API Reference

PropTypeDefaultDescription
size
"sm" | "md" | "lg"
"md"
The size of the slider.
valueLabel
boolean | ((value: number[]) => string)
false
Weather to display the value label. A function may be provided to customize the value label.
label
ReactNode
The content to display as the label.
description
ReactNode
A description for the field. Provides a hint such as specific requirements for what to choose.
formatOptions
Intl.NumberFormatOptions
-
The display format of the value label.
orientation
'horizontal' | 'vertical'
'horizontal'
The orientation of the Slider.
isDisabled
boolean
-
Whether the whole Slider is disabled.
minValue
number
0
The slider's minimum value.
maxValue
number
100
The slider's maximum value.
step
number
1
The slider's step value.
value
T
-
The current value (controlled).
defaultValue
T
-
The default value (uncontrolled).
name
string
-
The name of the input element, used when submitting an HTML form.
children
ReactNode | (values: SliderRenderProps & {defaultChildren: ReactNode | undefined}) => ReactNode
-
The children of the component. A function may be provided to alter the children based on component state.
className
string | (values: SliderRenderProps & {defaultClassName: string | undefined}) => string
-
The CSS className for the element. A function may be provided to compute the class based on component state.
style
CSSProperties | (values: SliderRenderProps & {defaultStyle: CSSProperties}) => CSSProperties
-
The inline style for the element. A function may be provided to compute the style based on component state.
EventTypeDescription
onChange
(value: T) => void
Handler that is called when the value changes.
onChangeEnd
(value: T) => void
Fired when the slider stops moving, due to being let go.
Data attributeDescription
[data-orientation="horizontal | vertical"]
The orientation of the slider.
[data-disabled]
Whether the slider is disabled.

Accessibility

Keyboard interactions

KeyDescription
Tab
Places focus on the handle. If the handle is already in focus, moves focus to the next handle or next element in the page tab sequence.
Shift+Tab
Places focus on the previous handle or previous element in the page tab sequence.
ArrowUp ArrowDown ArrowLeft ArrowRight
Moves the handle up/down/left/right.

Last updated on 10/11/2024

SwitchMenu