Skip to contents
1.0.0-beta.4GitHub

Slider

An easily stylable range input.

View as Markdown

Anatomy

Import the component and assemble its parts:

Anatomy

API reference

Root

Groups all parts of the slider. Renders a <div> element.

name

string

—
Name
name
Description

Identifies the field when a form is submitted.

Type
string | undefined
defaultValue

number | number[]

—
Name
defaultValue
Description

The uncontrolled value of the slider when it’s initially rendered.

To render a controlled slider, use the value prop instead.

Type
number | number[] | undefined
value

number | number[]

—
Name
value
Description

The value of the slider. For ranged sliders, provide an array with two values.

Type
number | number[] | undefined
onValueChange

function

—
Name
onValueChange
Description

Callback function that is fired when the slider's value changed. You can pull out the new value by accessing event.target.value (any).

Type
| ((
    value: number | number[],
    eventDetails: {
      reason: 'none'
      event: ReasonToEvent
      cancel: () => void
      allowPropagation: () => void
      isCanceled: boolean
      isPropagationAllowed: boolean
      trigger: HTMLElement | undefined
    } & { activeThumbIndex: number },
  ) => void)
| undefined
onValueCommitted

function

—
Name
onValueCommitted
Description

Callback function that is fired when the pointerup is triggered. Warning: This is a generic event not a change event.

Type
| ((
    value: number | number[],
    eventDetails: Slider.Root.CommitEventDetails,
  ) => void)
| undefined
locale

Intl.LocalesArgument

—
Name
locale
Description

The locale used by Intl.NumberFormat when formatting the value. Defaults to the user's runtime locale.

Type
Intl.LocalesArgument | undefined
ref

RefObject<HTMLDivElement>

—
Name
ref
Type
React.RefObject<HTMLDivElement> | undefined
thumbAlignment

Union

'center'

Name
thumbAlignment
Description

How the thumb(s) are aligned relative to Slider.Control when the value is at min or max:

  • center: The center of the thumb is aligned with the control edge
  • edge: The thumb is inset within the control such that its edge is aligned with the control edge
  • edge-client-only: Same as edge but renders after React hydration on the client, reducing bundle size in return
Type
'center' | 'edge' | 'edge-client-only' | undefined
Default

'center'

step

number

1

Name
step
Description

The granularity with which the slider can step through values. (A "discrete" slider.) The min prop serves as the origin for the valid values. We recommend (max - min) to be evenly divisible by the step.

Type
number | undefined
Default

1

largeStep

number

10

Name
largeStep
Description

The granularity with which the slider can step through values when using Page Up/Page Down or Shift + Arrow Up/Arrow Down.

Type
number | undefined
Default

10

minStepsBetweenValues

number

0

Name
minStepsBetweenValues
Description

The minimum steps between values in a range slider.

Type
number | undefined
Default

0

min

number

0

Name
min
Description

The minimum allowed value of the slider. Should not be equal to max.

Type
number | undefined
Default

0

max

number

100

Name
max
Description

The maximum allowed value of the slider. Should not be equal to min.

Type
number | undefined
Default

100

format

Intl.NumberFormatOptions

—
Name
format
Description

Options to format the input value.

Type
Intl.NumberFormatOptions | undefined
disabled

boolean

false

Name
disabled
Description

Whether the slider should ignore user interaction.

Type
boolean | undefined
Default

false

orientation

Orientation

'horizontal'

Name
orientation
Description

The component orientation.

Type
'horizontal' | 'vertical' | undefined
Default

'horizontal'

className

string | function

—
Name
className
Description

CSS class applied to the element, or a function that returns a class based on the component’s state.

Type
string | ((state: Slider.Root.State) => string)
render

ReactElement | function

—
Name
render
Description

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Type
| ReactElement
| ((
    props: HTMLProps,
    state: Slider.Root.State,
  ) => ReactElement)
data-dragging

Present while the user is dragging.

data-orientation

Indicates the orientation of the slider.

data-disabled

Present when the slider is disabled.

data-readonly

Present when the slider is readonly.

data-required

Present when the slider is required.

data-valid

Present when the slider is in valid state (when wrapped in Field.Root).

data-invalid

Present when the slider is in invalid state (when wrapped in Field.Root).

data-dirty

Present when the slider's value has changed (when wrapped in Field.Root).

data-touched

Present when the slider has been touched (when wrapped in Field.Root).

data-focused

Present when the slider is focused (when wrapped in Field.Root).

Value

Displays the current value of the slider as text. Renders an <output> element.

children

((formattedValues: string[], values: number[]) => ReactNode) | null

—
Name
children
Type
| ((
    formattedValues: string[],
    values: number[],
  ) => ReactNode)
| null
| undefined
className

string | function

—
Name
className
Description

CSS class applied to the element, or a function that returns a class based on the component’s state.

Type
string | ((state: Slider.Root.State) => string)
render

ReactElement | function

—
Name
render
Description

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Type
| ReactElement
| ((
    props: HTMLProps,
    state: Slider.Root.State,
  ) => ReactElement)
data-dragging

Present while the user is dragging.

data-orientation

Indicates the orientation of the slider.

data-disabled

Present when the slider is disabled.

data-readonly

Present when the slider is readonly.

data-required

Present when the slider is required.

data-valid

Present when the slider is in valid state (when wrapped in Field.Root).

data-invalid

Present when the slider is in invalid state (when wrapped in Field.Root).

data-dirty

Present when the slider's value has changed (when wrapped in Field.Root).

data-touched

Present when the slider has been touched (when wrapped in Field.Root).

data-focused

Present when the slider is focused (when wrapped in Field.Root).

Control

The clickable, interactive part of the slider. Renders a <div> element.

className

string | function

—
Name
className
Description

CSS class applied to the element, or a function that returns a class based on the component’s state.

Type
string | ((state: Slider.Root.State) => string)
render

ReactElement | function

—
Name
render
Description

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Type
| ReactElement
| ((
    props: HTMLProps,
    state: Slider.Root.State,
  ) => ReactElement)
data-dragging

Present while the user is dragging.

data-orientation

Indicates the orientation of the slider.

data-disabled

Present when the slider is disabled.

data-readonly

Present when the slider is readonly.

data-required

Present when the slider is required.

data-valid

Present when the slider is in valid state (when wrapped in Field.Root).

data-invalid

Present when the slider is in invalid state (when wrapped in Field.Root).

data-dirty

Present when the slider's value has changed (when wrapped in Field.Root).

data-touched

Present when the slider has been touched (when wrapped in Field.Root).

data-focused

Present when the slider is focused (when wrapped in Field.Root).

Track

Contains the slider indicator and represents the entire range of the slider. Renders a <div> element.

className

string | function

—
Name
className
Description

CSS class applied to the element, or a function that returns a class based on the component’s state.

Type
string | ((state: Slider.Root.State) => string)
render

ReactElement | function

—
Name
render
Description

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Type
| ReactElement
| ((
    props: HTMLProps,
    state: Slider.Root.State,
  ) => ReactElement)
data-dragging

Present while the user is dragging.

data-orientation

Indicates the orientation of the slider.

data-disabled

Present when the slider is disabled.

data-readonly

Present when the slider is readonly.

data-required

Present when the slider is required.

data-valid

Present when the slider is in valid state (when wrapped in Field.Root).

data-invalid

Present when the slider is in invalid state (when wrapped in Field.Root).

data-dirty

Present when the slider's value has changed (when wrapped in Field.Root).

data-touched

Present when the slider has been touched (when wrapped in Field.Root).

data-focused

Present when the slider is focused (when wrapped in Field.Root).

Indicator

Visualizes the current value of the slider. Renders a <div> element.

className

string | function

—
Name
className
Description

CSS class applied to the element, or a function that returns a class based on the component’s state.

Type
string | ((state: Slider.Root.State) => string)
render

ReactElement | function

—
Name
render
Description

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Type
| ReactElement
| ((
    props: HTMLProps,
    state: Slider.Root.State,
  ) => ReactElement)
data-dragging

Present while the user is dragging.

data-orientation

Indicates the orientation of the slider.

data-disabled

Present when the slider is disabled.

data-readonly

Present when the slider is readonly.

data-required

Present when the slider is required.

data-valid

Present when the slider is in valid state (when wrapped in Field.Root).

data-invalid

Present when the slider is in invalid state (when wrapped in Field.Root).

data-dirty

Present when the slider's value has changed (when wrapped in Field.Root).

data-touched

Present when the slider has been touched (when wrapped in Field.Root).

data-focused

Present when the slider is focused (when wrapped in Field.Root).

Thumb

The draggable part of the the slider at the tip of the indicator. Renders a <div> element and a nested <input type="range">.

getAriaLabel

function

—
Name
getAriaLabel
Description

A function which returns a string value for the aria-label attribute of the input.

Type
((index: number) => string) | null | undefined
getAriaValueText

function

—
Name
getAriaValueText
Description

A function which returns a string value for the aria-valuetext attribute of the input. This is important for screen reader users.

Type
| ((
    formattedValue: string,
    value: number,
    index: number,
  ) => string)
| null
| undefined
index

number

—
Name
index
Description

The index of the thumb which corresponds to the index of its value in the value or defaultValue array. This prop is required to support server-side rendering for range sliders with multiple thumbs.

Type
number | undefined
Example
onBlur

function

—
Name
onBlur
Description

A blur handler forwarded to the input.

Type
| React.FocusEventHandler<HTMLInputElement>
| undefined
onFocus

function

—
Name
onFocus
Description

A focus handler forwarded to the input.

Type
| React.FocusEventHandler<HTMLInputElement>
| undefined
tabIndex

number

—
Name
tabIndex
Description

Optional tab index attribute forwarded to the input.

Type
number | undefined
disabled

boolean

false

Name
disabled
Description

Whether the thumb should ignore user interaction.

Type
boolean | undefined
Default

false

inputRef

Ref<HTMLInputElement>

—
Name
inputRef
Description

A ref to access the nested input element.

Type
React.Ref<HTMLInputElement> | undefined
className

string | function

—
Name
className
Description

CSS class applied to the element, or a function that returns a class based on the component’s state.

Type
string | ((state: Slider.Thumb.State) => string)
render

ReactElement | function

—
Name
render
Description

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Type
| ReactElement
| ((
    props: HTMLProps,
    state: Slider.Thumb.State,
  ) => ReactElement)
data-dragging

Present while the user is dragging.

data-orientation

Indicates the orientation of the slider.

data-disabled

Present when the slider is disabled.

data-readonly

Present when the slider is readonly.

data-required

Present when the slider is required.

data-valid

Present when the slider is in valid state (when wrapped in Field.Root).

data-invalid

Present when the slider is in invalid state (when wrapped in Field.Root).

data-dirty

Present when the slider's value has changed (when wrapped in Field.Root).

data-touched

Present when the slider has been touched (when wrapped in Field.Root).

data-focused

Present when the slider is focused (when wrapped in Field.Root).

data-index

Indicates the index of the thumb in range sliders.

Examples

Range slider

To create a range slider:

  1. Pass an array of values and place a <Slider.Thumb> for each value in the array
  2. Additionally for server-side rendering, specify a numeric index for each thumb that corresponds to the index of its value in the value array

Thumb alignment

Set thumbAlignment="edge" to inset the thumb such that its edge aligns with the edge of the control when the value is at min or max, without overflowing the control like the default "center" alignment.

A client-only alternative thumbAlignment="edge-client-only" can be used to reduce bundle size but only renders after React hydration.