Skip to content

Slider (Range)

Slider - SliderInput - SliderTrack - SliderTrackHighlight - SliderMarker - SliderHandle

A UI input component where the user selects a value from within a given range. A Slider has a handle that can be moved along a track to change its value. When the user's mouse or focus is on the Slider's handle, the value can be incremented with keyboard controls.

Sliders are composed by an outer Slider component with a SliderTrack child component. SliderTrack can accept SliderTrackHighlight, SliderMarker and SliderHandle components as children.

Pointer Events: Slider uses pointer events for unified event handling across different pointer types (mouse, touch, stylus, etc.). As such, to override default behavior you will need to use pointer events rather than mouse or touch events. For example, if you wish to call event.preventDefault to override the slider handle's activation on a mouse click event, you'll want to reach for onPointerDown instead of onMouseDown. If you need to support older browsers without native pointer events (or ensure compatibility with some inconsistent native behavior in MacOS Safari < 13 and Safari), we recommend pepjs as a polyfill.

You can use Slider as a simple standalone component, or compose its parts with SliderInput.

Installation

npm install @reach/slider
# or
yarn add @reach/slider

And then import the components you need:

import {
  Slider,
  SliderTrack,
  SliderTrackHighlight,
  SliderHandle
} from "@reach/slider";

Usage

Slider

High-level component to render a slider in its simplest form. This works simililarly to a native HTML range input.

<Slider min={0} max={100} />

Slider Props

PropTypeRequiredDefault
childrennodetrue
defaultValuenumberfalse
disabledbooleanfalse
getValueTextfuncfalse
handleAlignment`'center''contain'`false
maxnumberfalse100
minnumberfalse0
namestringfalse
onChangefuncfalse
orientation`'horizontal''vertical'`false
stepnumberfalse
valuenumberfalse

Controlled Slider

If you want to control the slider's value, you can do so by passing a value and onChange handler similar to form inputs.

const [value, setValue] = useState(0);
<Slider onChange={setValue} value={value} min={0} max={100} />;

Slider Props

PropTypeRequiredDefault
childrennodetrue
defaultValuenumberfalse
disabledbooleanfalse
getValueTextfuncfalse
handleAlignment`'center''contain'`false
maxnumberfalse100
minnumberfalse0
namestringfalse
onChangefuncfalse
orientation`'horizontal''vertical'`false
stepnumberfalse
valuenumberfalse

Slider children

Type: node

Slider can accept SliderMarker children to enhance display of specific values along the track.

<Slider min={0} max={100}>
  {new Array(11).fill("x").map((x, index) => (
    <SliderMarker value={index * 10}>
      <span>{index * 10}</span>
    </SliderMarker>
  ))}
</Slider>

Slider defaultValue

Type: number

The defaultValue is used to set an initial value for an uncontrolled Slider.

Slider disabled

Type: boolean

Whether or not the slider should be disabled from user interaction.

Slider getValueText

Type: func: (value: number) => string

A function used to set human readable value text based on the slider's current value.

Slider handleAlignment

Type: 'center' | 'contain'

When set to center, the slider's handle will be positioned directly centered over the slider's curremt value on the track. This means that when the slider is at its min or max value, a visiable slider handle will extend beyond the width (or height in vertical mode) of the slider track. When set to contain, the slider handle will always be contained within the bounds of the track, meaning its position will be slightly offset from the actual value depending on where it sits on the track.

Slider max

Type: number

The maximum value of the slider. Defaults to 100.

Slider min

Type: number

The minimum value of the slider. Defaults to 0.

Slider name

Type: string

If the slider is used as a form input, it should accept a name prop to identify its value in context of the form.

Slider onChange

Type: func: (value, { min, max, handlePosition }) => void

Callback that fires when the slider value changes. When the value prop is set, the Slider state becomes controlled and onChange must be used to update the value in response to user interaction.

Slider orientation

Type: 'horizontal' | 'vertical'

Sets the slider to horizontal or vertical mode.

Slider step

Type: number

The step attribute is a number that specifies the granularity that the value must adhere to as it changes. Step sets minimum intervals of change, creating a "snap" effect when the handle is moved along the track.

Slider value

Type: number

An explicit value for the slider. When this prop is used, the Slider state becomes controlled and onChange must be used to update the value in response to user interaction.

Slider CSS Selectors

Please see the styling guide.

[data-reach-slider] {
}
[data-reach-slider-disabled] {
}
[data-reach-slider-orientation="horizontal|vertical"] {
}

SliderInput

The parent component of the slider interface. This is a lower level component if you need more control over styles or rendering the slider's inner components.

SliderInput Props

SliderInput accepts the same props as Slider.

SliderInput children

Type: node | func: (args: SliderArgs) => node

Slider expects <SliderTrack> as its child; The track will accept all additional slider sub-components as children. It can also accept a function/render prop as its child to expose some of its internal state variables.

SliderArgs = { hasFocus: boolean, id: string, max: number, min: number, value: number, valueText: string }

SliderInput CSS Selectors

See selectors for Slider.

SliderTrack

The parent component of the slider's inner components. Represents the visual track on which the slider's handle moves to represent its value.

SliderTrack CSS Selectors

Please see the styling guide.

[data-reach-slider-track] {
}
[data-reach-slider-track-disabled] {
}
[data-reach-slider-track-orientation="horizontal|vertical"] {
}

SliderTrack Props

PropTypeRequiredDefault
childrennodetrue

SliderTrack children

Type: node

SliderTrack expects <SliderHandle>, at minimum, for the Slider to function. All other Slider subcomponents should be passed as children inside the SliderTrack.

SliderTrackHighlight

The (typically) highlighted portion of the track that represents the space between the slider's min value and its current value.

SliderTrackHighlight CSS Selectors

Please see the styling guide.

[data-reach-slider-track-highlight] {
}
[data-reach-slider-track-highlight-disabled] {
}
[data-reach-slider-track-highlight-orientation="horizontal|vertical"] {
}

SliderTrackHighlight Props

SliderTrackHighlight accepts any props that a HTML div component accepts. SliderTrackHighlight will not accept or render any children.

SliderMarker

A fixed value marker. These can be used to illustrate a range of steps or highlight important points along the slider track.

SliderMarker CSS Selectors

Please see the styling guide.

[data-reach-slider-marker] {
}
[data-reach-slider-marker-disabled] {
}
[data-reach-slider-marker-orientation="horizontal|vertical"] {
}

/* Applied to a marker when the slider value exceeds the marker value */
[data-reach-slider-marker-highlight] {
}

SliderMarker Props

PropTypeRequiredDefault
valuenumbertrue

SliderMarker value

Type: number

The value to denote where the marker should appear along the track.

SliderHandle

The handle that the user drags along the track to set the slider value.

SliderHandle CSS Selectors

Please see the styling guide.

[data-reach-slider-handle] {
}
[data-reach-slider-handle-disabled] {
}
[data-reach-slider-handle-orientation="horizontal|vertical"] {
}

SliderHandle Props

SliderTrackHighlight accepts any props that a HTML div component accepts.