alpha

useSlider

Provides the behavior and accessibility implementation for a slider component representing one or more values.

install	`yarn add @react-aria/slider`
version	3.0.0-alpha.3
usage	`import {useSlider, useSliderThumb} from '@react-aria/slider'`

View ARIA spec

API#

useSlider(
  props: SliderProps,
  state: SliderState,
  trackRef: RefObject<HTMLElement>
): SliderAria

useSliderThumb(
  (opts: SliderThumbOptions,
  , state: SliderState
)): SliderThumbAria

Features#

The <input type="range"> HTML element can be used to build a slider, however it is very difficult to style cross browser. useSlider and useSliderThumb help achieve accessible sliders that can be styled as needed.

Support for mouse, touch, and keyboard via the useMove hook
Exposed to assistive technology as a group of slider elements via ARIA
Slider thumbs use hidden native input elements to support touch screen readers
Labeling support for accessibility
Internationalized number formatting as a percentage or value
Support for multiple thumbs, e.g. a group of range values
Support for both horizontal and vertical orientations
Prevents text selection while dragging

Anatomy#

Sliders consist of a track element showing the range of available values, one or more thumb thumbs showing the current values, an optional <output> element displaying the current values textually, and a 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.

useSlider hook#

useSlider returns three sets of props that you should spread onto the appropriate element:

Name	Type	Description
`labelProps`	`LabelHTMLAttributes<HTMLLabelElement>`	Props for the label element.
`containerProps`	`HTMLAttributes<HTMLElement>`	Props for the root element of the slider component; groups slider inputs.
`trackProps`	`HTMLAttributes<HTMLElement>`	Props for the track element.
`outputProps`	`OutputHTMLAttributes<HTMLOutputElement>`	Props for the output element, displaying the value of the slider thumbs.

If there is no visual label, an aria-label or aria-labelledby prop must be passed instead to identify the element to screen readers.

useSliderThumb hook#

useSliderThumb returns three sets of props that you should spread onto the appropriate element:

Name	Type	Description
`inputProps`	`HTMLAttributes<HTMLElement>`	Props for the range input.
`thumbProps`	`HTMLAttributes<HTMLElement>`	Props for the root thumb element; handles the dragging motion.
`labelProps`	`HTMLAttributes<HTMLElement>`	Props for the label element for this thumb.

If there is no visual label, an aria-label or aria-labelledby prop must be passed instead to identify each thumb to screen readers.

Slider state is managed by the useSliderState hook.

Examples#

Single Thumb#

import {useSliderState} from '@react-stately/slider';
import {useFocusRing} from '@react-aria/focus';
import {VisuallyHidden} from '@react-aria/visually-hidden';
import {mergeProps} from '@react-aria/utils';

function Slider(props) {
  let trackRef = React.useRef(null);

  let numberFormatter = new Intl.NumberFormat('en-US', props.formatOptions);
  let state = useSliderState({...props, numberFormatter});
  let {containerProps, trackProps, labelProps, outputProps} = useSlider(
    props,
    state,
    trackRef
  );

  return (
    <div
      {...containerProps}
      style={{
        position: 'relative',
        display: 'flex',
        flexDirection: 'column',
        alignItems: 'center',
        width: 300,
        touchAction: 'none'
      }}>
      <div style={{display: 'flex', alignSelf: 'stretch'}}>
        {props.label && <label {...labelProps}>{props.label}</label>}
        <output {...outputProps} style={{flex: '1 0 auto', textAlign: 'end'}}>
          {state.getThumbValueLabel(0)}
        </output>
      </div>
      <div style={{position: 'relative', width: '100%'}}>
        <div
          style={{
            position: 'absolute',
            backgroundColor: 'gray',
            height: 3,
            top: 13,
            width: '100%'
          }}
        />
        <div
          {...trackProps}
          ref={trackRef}
          style={{
            position: 'relative',
            height: 30,
            width: ' 100%'
          }}
        />
        <Thumb index={0} state={state} trackRef={trackRef} />
      </div>
    </div>
  );
}

function Thumb(props) {
  let {state, trackRef, index} = props;
  let inputRef = React.useRef(null);
  let {thumbProps, inputProps} = useSliderThumb(
    {
      index,
      trackRef,
      inputRef
    },
    state
  );

  let {focusProps, isFocusVisible} = useFocusRing();
  return (
    <div
      style={{
        position: 'absolute',
        top: 4,
        transform: 'translateX(-50%)',
        left: `${state.getThumbPercent(index) * 100}%`
      }}>
      <div
        {...thumbProps}
        style={{
          width: 20,
          height: 20,
          borderRadius: '50%',
          backgroundColor: isFocusVisible
            ? 'orange'
            : state.isThumbDragging(index)
            ? 'dimgrey'
            : 'gray'
        }}>
        <VisuallyHidden>
          <input ref={inputRef} {...mergeProps(inputProps, focusProps)} />
        </VisuallyHidden>
      </div>
    </div>
  );
}

<Slider
  label="Opacity"
  formatOptions={{style: 'percent'}}
  maxValue={1}
  step={0.01}
/>

import {useSliderState} from '@react-stately/slider';
import {useFocusRing} from '@react-aria/focus';
import {VisuallyHidden} from '@react-aria/visually-hidden';
import {mergeProps} from '@react-aria/utils';

function Slider(props) {
  let trackRef = React.useRef(null);

  let numberFormatter = new Intl.NumberFormat(
    'en-US',
    props.formatOptions
  );
  let state = useSliderState({...props, numberFormatter});
  let {
    containerProps,
    trackProps,
    labelProps,
    outputProps
  } = useSlider(props, state, trackRef);

  return (
    <div
      {...containerProps}
      style={{
        position: 'relative',
        display: 'flex',
        flexDirection: 'column',
        alignItems: 'center',
        width: 300,
        touchAction: 'none'
      }}>
      <div style={{display: 'flex', alignSelf: 'stretch'}}>
        {props.label && (
          <label {...labelProps}>{props.label}</label>
        )}
        <output
          {...outputProps}
          style={{flex: '1 0 auto', textAlign: 'end'}}>
          {state.getThumbValueLabel(0)}
        </output>
      </div>
      <div style={{position: 'relative', width: '100%'}}>
        <div
          style={{
            position: 'absolute',
            backgroundColor: 'gray',
            height: 3,
            top: 13,
            width: '100%'
          }}
        />
        <div
          {...trackProps}
          ref={trackRef}
          style={{
            position: 'relative',
            height: 30,
            width: ' 100%'
          }}
        />
        <Thumb
          index={0}
          state={state}
          trackRef={trackRef}
        />
      </div>
    </div>
  );
}

function Thumb(props) {
  let {state, trackRef, index} = props;
  let inputRef = React.useRef(null);
  let {thumbProps, inputProps} = useSliderThumb(
    {
      index,
      trackRef,
      inputRef
    },
    state
  );

  let {focusProps, isFocusVisible} = useFocusRing();
  return (
    <div
      style={{
        position: 'absolute',
        top: 4,
        transform: 'translateX(-50%)',
        left: `${state.getThumbPercent(index) * 100}%`
      }}>
      <div
        {...thumbProps}
        style={{
          width: 20,
          height: 20,
          borderRadius: '50%',
          backgroundColor: isFocusVisible
            ? 'orange'
            : state.isThumbDragging(index)
            ? 'dimgrey'
            : 'gray'
        }}>
        <VisuallyHidden>
          <input
            ref={inputRef}
            {...mergeProps(inputProps, focusProps)}
          />
        </VisuallyHidden>
      </div>
    </div>
  );
}

<Slider
  label="Opacity"
  formatOptions={{style: 'percent'}}
  maxValue={1}
  step={0.01}
/>

import {useSliderState} from '@react-stately/slider';
import {useFocusRing} from '@react-aria/focus';
import {VisuallyHidden} from '@react-aria/visually-hidden';
import {mergeProps} from '@react-aria/utils';

function Slider(props) {
  let trackRef = React.useRef(
    null
  );

  let numberFormatter = new Intl.NumberFormat(
    'en-US',
    props.formatOptions
  );
  let state = useSliderState(
    {
      ...props,
      numberFormatter
    }
  );
  let {
    containerProps,
    trackProps,
    labelProps,
    outputProps
  } = useSlider(
    props,
    state,
    trackRef
  );

  return (
    <div
      {...containerProps}
      style={{
        position:
          'relative',
        display: 'flex',
        flexDirection:
          'column',
        alignItems:
          'center',
        width: 300,
        touchAction:
          'none'
      }}>
      <div
        style={{
          display:
            'flex',
          alignSelf:
            'stretch'
        }}>
        {props.label && (
          <label
            {...labelProps}>
            {props.label}
          </label>
        )}
        <output
          {...outputProps}
          style={{
            flex:
              '1 0 auto',
            textAlign:
              'end'
          }}>
          {state.getThumbValueLabel(
            0
          )}
        </output>
      </div>
      <div
        style={{
          position:
            'relative',
          width: '100%'
        }}>
        <div
          style={{
            position:
              'absolute',
            backgroundColor:
              'gray',
            height: 3,
            top: 13,
            width: '100%'
          }}
        />
        <div
          {...trackProps}
          ref={trackRef}
          style={{
            position:
              'relative',
            height: 30,
            width:
              ' 100%'
          }}
        />
        <Thumb
          index={0}
          state={state}
          trackRef={
            trackRef
          }
        />
      </div>
    </div>
  );
}

function Thumb(props) {
  let {
    state,
    trackRef,
    index
  } = props;
  let inputRef = React.useRef(
    null
  );
  let {
    thumbProps,
    inputProps
  } = useSliderThumb(
    {
      index,
      trackRef,
      inputRef
    },
    state
  );

  let {
    focusProps,
    isFocusVisible
  } = useFocusRing();
  return (
    <div
      style={{
        position:
          'absolute',
        top: 4,
        transform:
          'translateX(-50%)',
        left: `${
          state.getThumbPercent(
            index
          ) * 100
        }%`
      }}>
      <div
        {...thumbProps}
        style={{
          width: 20,
          height: 20,
          borderRadius:
            '50%',
          backgroundColor: isFocusVisible
            ? 'orange'
            : state.isThumbDragging(
                index
              )
            ? 'dimgrey'
            : 'gray'
        }}>
        <VisuallyHidden>
          <input
            ref={
              inputRef
            }
            {...mergeProps(
              inputProps,
              focusProps
            )}
          />
        </VisuallyHidden>
      </div>
    </div>
  );
}

<Slider
  label="Opacity"
  formatOptions={{
    style: 'percent'
  }}
  maxValue={1}
  step={0.01}
/>

Multi Thumb#

function RangeSlider(props) {
  let trackRef = React.useRef(null);

  let numberFormatter = new Intl.NumberFormat('en-US', props.formatOptions);
  let state = useSliderState({...props, numberFormatter});
  let {containerProps, trackProps, labelProps, outputProps} = useSlider(
    props,
    state,
    trackRef
  );

  return (
    <div
      {...containerProps}
      style={{
        position: 'relative',
        display: 'flex',
        flexDirection: 'column',
        alignItems: 'center',
        width: 300,
        touchAction: 'none'
      }}>
      <div style={{display: 'flex', alignSelf: 'stretch'}}>
        {props.label && <label {...labelProps}>{props.label}</label>}
        <output {...outputProps} style={{flex: '1 0 auto', textAlign: 'end'}}>
          {`${state.getThumbValueLabel(0)} - ${state.getThumbValueLabel(1)}`}
        </output>
      </div>
      <div style={{position: 'relative', width: '100%'}}>
        <div
          style={{
            position: 'absolute',
            backgroundColor: 'grey',
            height: 3,
            top: 13,
            width: '100%'
          }}
        />
        <div
          {...trackProps}
          ref={trackRef}
          style={{
            position: 'relative',
            height: 30,
            width: ' 100%'
          }}
        />
        <Thumb index={0} state={state} trackRef={trackRef} />
        <Thumb index={1} state={state} trackRef={trackRef} />
      </div>
    </div>
  );
}

<RangeSlider
  label="Price Range"
  formatOptions={{style: 'currency', currency: 'USD'}}
  maxValue={500}
  defaultValue={[100, 350]}
  step={10}
/>

function RangeSlider(props) {
  let trackRef = React.useRef(null);

  let numberFormatter = new Intl.NumberFormat(
    'en-US',
    props.formatOptions
  );
  let state = useSliderState({...props, numberFormatter});
  let {
    containerProps,
    trackProps,
    labelProps,
    outputProps
  } = useSlider(props, state, trackRef);

  return (
    <div
      {...containerProps}
      style={{
        position: 'relative',
        display: 'flex',
        flexDirection: 'column',
        alignItems: 'center',
        width: 300,
        touchAction: 'none'
      }}>
      <div style={{display: 'flex', alignSelf: 'stretch'}}>
        {props.label && (
          <label {...labelProps}>{props.label}</label>
        )}
        <output
          {...outputProps}
          style={{flex: '1 0 auto', textAlign: 'end'}}>
          {`${state.getThumbValueLabel(
            0
          )} - ${state.getThumbValueLabel(1)}`}
        </output>
      </div>
      <div style={{position: 'relative', width: '100%'}}>
        <div
          style={{
            position: 'absolute',
            backgroundColor: 'grey',
            height: 3,
            top: 13,
            width: '100%'
          }}
        />
        <div
          {...trackProps}
          ref={trackRef}
          style={{
            position: 'relative',
            height: 30,
            width: ' 100%'
          }}
        />
        <Thumb
          index={0}
          state={state}
          trackRef={trackRef}
        />
        <Thumb
          index={1}
          state={state}
          trackRef={trackRef}
        />
      </div>
    </div>
  );
}

<RangeSlider
  label="Price Range"
  formatOptions={{style: 'currency', currency: 'USD'}}
  maxValue={500}
  defaultValue={[100, 350]}
  step={10}
/>

function RangeSlider(
  props
) {
  let trackRef = React.useRef(
    null
  );

  let numberFormatter = new Intl.NumberFormat(
    'en-US',
    props.formatOptions
  );
  let state = useSliderState(
    {
      ...props,
      numberFormatter
    }
  );
  let {
    containerProps,
    trackProps,
    labelProps,
    outputProps
  } = useSlider(
    props,
    state,
    trackRef
  );

  return (
    <div
      {...containerProps}
      style={{
        position:
          'relative',
        display: 'flex',
        flexDirection:
          'column',
        alignItems:
          'center',
        width: 300,
        touchAction:
          'none'
      }}>
      <div
        style={{
          display:
            'flex',
          alignSelf:
            'stretch'
        }}>
        {props.label && (
          <label
            {...labelProps}>
            {props.label}
          </label>
        )}
        <output
          {...outputProps}
          style={{
            flex:
              '1 0 auto',
            textAlign:
              'end'
          }}>
          {`${state.getThumbValueLabel(
            0
          )} - ${state.getThumbValueLabel(
            1
          )}`}
        </output>
      </div>
      <div
        style={{
          position:
            'relative',
          width: '100%'
        }}>
        <div
          style={{
            position:
              'absolute',
            backgroundColor:
              'grey',
            height: 3,
            top: 13,
            width: '100%'
          }}
        />
        <div
          {...trackProps}
          ref={trackRef}
          style={{
            position:
              'relative',
            height: 30,
            width:
              ' 100%'
          }}
        />
        <Thumb
          index={0}
          state={state}
          trackRef={
            trackRef
          }
        />
        <Thumb
          index={1}
          state={state}
          trackRef={
            trackRef
          }
        />
      </div>
    </div>
  );
}

<RangeSlider
  label="Price Range"
  formatOptions={{
    style: 'currency',
    currency: 'USD'
  }}
  maxValue={500}
  defaultValue={[
    100,
    350
  ]}
  step={10}
/>

Internationalization#

Value formatting#

Formatting the value that should be displayed in the value label or aria-valuetext is handled by useSliderState. The formatting can be controlled using the formatOptions prop. If you want to change locales, the I18nProvider must be somewhere in the hierarchy above the Slider. This will tell the formatter what locale to use.

RTL#

In right-to-left languages, the slider should be mirrored. The label is right-aligned, the value is left-aligned. Ensure that your CSS accounts for this.

Name	Type	Default	Description
`minValue`	`number`	`0`	The slider's minimum value.
`maxValue`	`number`	`100`	The slider's maximum value.
`step`	`number`	`1`	The slider's step value.
`orientation`	`Orientation`	`'horizontal'`	The orientation of the Slider.
`isDisabled`	`boolean`	—	Whether the whole Slider is disabled.
`onChangeEnd`	`( (value: T )) => void`	—	Fired when the slider stops moving, due to being let go.
`label`	`ReactNode`	—	The content to display as the label.
`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.
`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.
`value`	`T`	—	The current value (controlled).
`defaultValue`	`T`	—	The default value (uncontrolled).
`onChange`	`( (value: T )) => void`	—	Handler that is called when the value changes.

'horizontal' | 'vertical'

Properties

Name	Type	Description
`values`	`number[]`	Values managed by the slider by thumb index.
`focusedThumb`	`number \| undefined`	Currently-focused thumb index.
`step`	`number`	The step amount for the slider.

Methods

Method	Description
`getThumbValue( (index: number )): number`	Get the value for the specified thumb.
`setThumbValue( (index: number, , value: number )): void`	Sets the value for the specified thumb. The actual value set will be clamped and rounded according to min/max/step.
`setThumbPercent( (index: number, , percent: number )): void`	Sets value for the specified thumb by percent offset (between 0 and 1).
`isThumbDragging( (index: number )): boolean`	Whether the specific thumb is being dragged.
`setThumbDragging( (index: number, , dragging: boolean )): void`	Set is dragging on the specified thumb.
`setFocusedThumb( (index: number \| \| undefined )): void`	Set focused true on specified thumb. This will remove focus from any thumb that had it before.
`getThumbPercent( (index: number )): number`	Returns the specified thumb's value as a percentage from 0 to 1.
`getValuePercent( (value: number )): number`	Returns the value as a percent between the min and max of the slider.
`getThumbValueLabel( (index: number )): string`	Returns the string label for the specified thumb's value, per props.formatOptions.
`getFormattedValue( (value: number )): string`	Returns the string label for the value, per props.formatOptions.
`getThumbMinValue( (index: number )): number`	Returns the min allowed value for the specified thumb.
`getThumbMaxValue( (index: number )): number`	Returns the max allowed value for the specified thumb.
`getPercentValue( (percent: number )): number`	Converts a percent along track (between 0 and 1) to the corresponding value.
`isThumbEditable( (index: number )): boolean`	Returns if the specified thumb is editable.
`setThumbEditable( (index: number, , editable: boolean )): void`	Set the specified thumb's editable state.

Name	Type	Description
`labelProps`	`LabelHTMLAttributes<HTMLLabelElement>`	Props for the label element.
`containerProps`	`HTMLAttributes<HTMLElement>`	Props for the root element of the slider component; groups slider inputs.
`trackProps`	`HTMLAttributes<HTMLElement>`	Props for the track element.
`outputProps`	`OutputHTMLAttributes<HTMLOutputElement>`	Props for the output element, displaying the value of the slider thumbs.

Name	Type	Default	Description
`trackRef`	`RefObject<HTMLElement>`	—	A ref to the track element.
`inputRef`	`RefObject<HTMLInputElement>`	—	A ref to the thumb input element.
`index`	`number`	—	Index of the thumb for accessing purposes.
`orientation`	`Orientation`	`'horizontal'`	The orientation of the Slider.
`isDisabled`	`boolean`	—	Whether the Thumb is disabled.
`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.
`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.
`excludeFromTabOrder`	`boolean`	—	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`id`	`string`	—	The element's unique identifier. See MDN.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`validationState`	`ValidationState`	—	Whether the input should display its "valid" or "invalid" visual styling.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission. Often paired with the `necessityIndicator` prop to add a visual indicator to the input.
`aria-errormessage`	`string`	—	Identifies the element that provides an error message for the object.
`label`	`ReactNode`	—	The content to display as the label.

BaseEvent<ReactKeyboardEvent<any>>

T & {stopPropagation: () => void,
continuePropagation: () => void
}

'valid' | 'invalid'

Name	Type	Description
`inputProps`	`HTMLAttributes<HTMLElement>`	Props for the range input.
`thumbProps`	`HTMLAttributes<HTMLElement>`	Props for the root thumb element; handles the dragging motion.
`labelProps`	`HTMLAttributes<HTMLElement>`	Props for the label element for this thumb.

Provides state management for a slider component. Stores values for all thumbs and formats values for localization and provides methods to update the position of any thumbs.

useSliderState(
  (props: SliderStateProps
)): SliderState

Name	Type	Default	Description
`numberFormatter`	`Intl.NumberFormat`	—
`minValue`	`number`	`0`	The slider's minimum value.
`maxValue`	`number`	`100`	The slider's maximum value.
`step`	`number`	`1`	The slider's step value.
`orientation`	`Orientation`	`'horizontal'`	The orientation of the Slider.
`isDisabled`	`boolean`	—	Whether the whole Slider is disabled.
`onChangeEnd`	`( (value: T )) => void`	—	Fired when the slider stops moving, due to being let go.
`label`	`ReactNode`	—	The content to display as the label.
`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.
`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.
`value`	`T`	—	The current value (controlled).
`defaultValue`	`T`	—	The default value (uncontrolled).
`onChange`	`( (value: T )) => void`	—	Handler that is called when the value changes.