Slider

An easily stylable range input.

import { Slider } from '@base-ui/react/slider';
import styles from './index.module.css';

export default function ExampleSlider() {
  return (
    <Slider.Root defaultValue={25}>
      <Slider.Control className={styles.Control}>
        <Slider.Track className={styles.Track}>
          <Slider.Indicator className={styles.Indicator} />
          <Slider.Thumb aria-label="Volume" className={styles.Thumb} />
        </Slider.Track>
      </Slider.Control>
    </Slider.Root>
  );
}

Usage guidelines

Form controls must have an accessible name: See Labeling a slider and the forms guide.

Anatomy

Import the component and assemble its parts:

Anatomy

import { Slider } from '@base-ui/react/slider';

<Slider.Root>
  <Slider.Value />
  <Slider.Control>
    <Slider.Track>
      <Slider.Indicator />
      <Slider.Thumb />
    </Slider.Track>
  </Slider.Control>
</Slider.Root>

Examples

Range slider

To create a range slider:

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

Thumbs can be configured to behave differently when they collide during pointer interactions using the thumbCollisionBehavior prop on <Slider.Root>.

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.

Labeling a slider

A single-thumb slider without a visible label (such as a volume control) can be labeled using aria-label on <Slider.Thumb>:

Slider with invisible label

<Slider.Root>
  <Slider.Control>
    <Slider.Track>
      <Slider.Indicator />
      <Slider.Thumb aria-label="Volume" />
    </Slider.Track>
  </Slider.Control>
</Slider.Root>

A visible label can be created using aria-labelledby on <Slider.Root> that references the id of a sibling element, such as a <div>:

Slider with visible label

<div id="volume-label">Volume</div>
<Slider.Root aria-labelledby="volume-label">
  <Slider.Control>
    <Slider.Track>
      <Slider.Indicator />
      <Slider.Thumb />
    </Slider.Track>
  </Slider.Control>
</Slider.Root>

For a multi-thumb range slider with a visible label, add aria-label on each <Slider.Thumb> to distinguish them:

Labeling multi-thumb range sliders

<div id="price-label">Price range</div>
<Slider.Root defaultValue={[25, 75]} aria-labelledby="price-label">
  <Slider.Control>
    <Slider.Track>
      <Slider.Indicator />
      <Slider.Thumb index={0} aria-label="Minimum price" />
      <Slider.Thumb index={1} aria-label="Maximum price" />
    </Slider.Track>
  </Slider.Control>
</Slider.Root>

The Field and Fieldset components can also be used to provide accessible labels for sliders, eliminating the need to track id or aria-labelledby associations manually. Field comes with a UX improvement to prevent double clicks from selecting the label text.

For a single-thumb slider, use Field to provide a visible label:

Using Field to label a slider

<Field.Root>
  <Field.Label>Volume</Field.Label>
  <Slider.Root>
    <Slider.Control>
      <Slider.Track>
        <Slider.Indicator />
        <Slider.Thumb />
      </Slider.Track>
    </Slider.Control>
  </Slider.Root>
</Field.Root>

For a multi-thumb range slider, use Fieldset by replacing the <Fieldset.Root> element with <Slider.Root> via the render prop. <Fieldset.Legend> provides the visible label for the group:

Using Fieldset to label a multi-thumb slider

<Field.Root>
  <Fieldset.Root render={<Slider.Root />}>
    <Fieldset.Legend>Price range</Fieldset.Legend>
    <Slider.Control>
      <Slider.Track>
        <Slider.Indicator />
        <Slider.Thumb index={0} aria-label="Minimum price" />
        <Slider.Thumb index={1} aria-label="Maximum price" />
      </Slider.Track>
    </Slider.Control>
  </Fieldset.Root>
</Field.Root>

Form integration

To use a slider in a form, pass the slider’s name to <Field.Root>:

Using Slider in a form

<Form>
  <Field.Root name="volume">
    <Field.Label>Volume</Field.Label>
    <Slider.Root>
      <Slider.Control>
        <Slider.Track>
          <Slider.Indicator />
          <Slider.Thumb />
        </Slider.Track>
      </Slider.Control>
    </Slider.Root>
  </Field.Root>
</Form>

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).

The eventDetails.reason indicates what triggered the change:

'input-change' when the hidden range input emits a change event (for example, via form integration)

'track-press' when the control track is pressed

'drag' while dragging a thumb

'keyboard' for keyboard input

'none' when the change is triggered without a specific interaction
Type: | (( value: number | number[], eventDetails: Slider.Root.ChangeEventDetails, ) => 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.

The eventDetails.reason indicates what triggered the commit:

'drag' while dragging a thumb

'track-press' when the control track is pressed

'keyboard' for keyboard input

'input-change' when the hidden range input emits a change event (for example, via form integration)

'none' when the commit occurs without a specific interaction
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

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'

thumbCollisionBehavior

Union

'push'

Name: thumbCollisionBehavior
Description: Controls how thumbs behave when they collide during pointer interactions.

'push' (default): Thumbs push each other without restoring their previous positions when dragged back.

'swap': Thumbs swap places when dragged past each other.

'none': Thumbs cannot move past each other; excess movement is ignored.
Type: 'push' | 'swap' | 'none' | undefined
Default: 'push'

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 | undefined) | undefined

style

React.CSSProperties | function

—

Name: style
Type: | React.CSSProperties | (( state: Slider.Root.State, ) => React.CSSProperties | undefined) | undefined

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) | undefined

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-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).

Attribute	Description	-
`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-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).

Additional Types

Slider.Root.Props

Re-Export of Root props as SliderRootProps

Slider.Root.State

type SliderRootState = {
  activeThumbIndex: number;
  disabled: boolean;
  dragging: boolean;
  max: number;
  min: number;
  minStepsBetweenValues: number;
  orientation: 'horizontal' | 'vertical';
  step: number;
  values: number[];
  touched: boolean;
  dirty: boolean;
  valid: boolean | null;
  filled: boolean;
  focused: boolean;
}

Slider.Root.ChangeEventReason

type SliderRootChangeEventReason = 'input-change' | 'track-press' | 'drag' | 'keyboard' | 'none';

Slider.Root.ChangeEventDetails

type SliderRootChangeEventDetails =
  | BaseUIChangeEventDetail<'none', SliderRootChangeEventCustomProperties>
  | BaseUIChangeEventDetail<'input-change', SliderRootChangeEventCustomProperties>
  | BaseUIChangeEventDetail<'track-press', SliderRootChangeEventCustomProperties>
  | BaseUIChangeEventDetail<'drag', SliderRootChangeEventCustomProperties>
  | BaseUIChangeEventDetail<'keyboard', SliderRootChangeEventCustomProperties>;

Slider.Root.CommitEventReason

type SliderRootCommitEventReason = 'input-change' | 'track-press' | 'drag' | 'keyboard' | 'none';

Slider.Root.CommitEventDetails

type SliderRootCommitEventDetails =
  | { reason: 'none'; event: Event }
  | { reason: 'input-change'; event: Event | InputEvent }
  | { reason: 'track-press'; event: PointerEvent | MouseEvent | TouchEvent }
  | { reason: 'drag'; event: PointerEvent | TouchEvent }
  | { reason: 'keyboard'; event: KeyboardEvent };

Value

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

children

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

—

Name: children
Type: ((formattedValues: string[], values: number[]) => React.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 | undefined) | undefined

style

React.CSSProperties | function

—

Name: style
Type: | React.CSSProperties | (( state: Slider.Root.State, ) => React.CSSProperties | undefined) | undefined

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) | undefined

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-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).

Attribute	Description	-
`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-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).

Additional Types

Slider.Value.Props

Re-Export of Value props as SliderValueProps

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 | undefined) | undefined

style

React.CSSProperties | function

—

Name: style
Type: | React.CSSProperties | (( state: Slider.Root.State, ) => React.CSSProperties | undefined) | undefined

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) | undefined

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-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).

Attribute	Description	-
`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-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).

Additional Types

Slider.Control.Props

Re-Export of Control props as SliderControlProps

Slider.Control.State

type SliderControlState = {
  activeThumbIndex: number;
  disabled: boolean;
  dragging: boolean;
  max: number;
  min: number;
  minStepsBetweenValues: number;
  orientation: 'horizontal' | 'vertical';
  step: number;
  values: number[];
  touched: boolean;
  dirty: boolean;
  valid: boolean | null;
  filled: boolean;
  focused: boolean;
}

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 | undefined) | undefined

style

React.CSSProperties | function

—

Name: style
Type: | React.CSSProperties | (( state: Slider.Root.State, ) => React.CSSProperties | undefined) | undefined

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) | undefined

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-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).

Attribute	Description	-
`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-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).

Additional Types

Slider.Track.Props

Re-Export of Track props as SliderTrackProps

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 | undefined) | undefined

style

React.CSSProperties | function

—

Name: style
Type: | React.CSSProperties | (( state: Slider.Root.State, ) => React.CSSProperties | undefined) | undefined

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) | undefined

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-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).

Attribute	Description	-
`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-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).

Additional Types

Slider.Indicator.Props

Re-Export of Indicator props as SliderIndicatorProps

Thumb

The draggable part of 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: <Slider.Root value={[10, 20]}> <Slider.Thumb index={0} /> <Slider.Thumb index={1} /> </Slider.Root>

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

React.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 | undefined) | undefined

style

React.CSSProperties | function

—

Name: style
Type: | React.CSSProperties | (( state: Slider.Thumb.State, ) => React.CSSProperties | undefined) | undefined

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) | undefined

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-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.

Attribute	Description	-
`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-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.

Additional Types

Slider.Thumb.Props

Re-Export of Thumb props as SliderThumbProps

Slider.Thumb.State

type SliderThumbState = {
  activeThumbIndex: number;
  disabled: boolean;
  dragging: boolean;
  max: number;
  min: number;
  minStepsBetweenValues: number;
  orientation: 'horizontal' | 'vertical';
  step: number;
  values: number[];
  touched: boolean;
  dirty: boolean;
  valid: boolean | null;
  filled: boolean;
  focused: boolean;
}