RangeInput

A slider: one value on a range, or two or more thumbs for a range of values.

Demos

For usage examples, visit the component demo page: RangeInput

Import

import { RangeInput } from '@soroush.tech/design-system/RangeInput'

Props

Prop	Type	Default	Description
`value`	`number \| number[]`	-	One thumb for a number, one per entry for an array - an empty one is a thumb at `min`. Controlled with `onChange`.
`defaultValue`	`number \| number[]`	`min`	The value at first, when uncontrolled.
`onChange`	`(event, value, activeThumb: number) => void`	-	Fired as the value changes. `event.target` is `{ value, name }`, as a form library reads it.
`onChangeCommitted`	`(event, value) => void`	-	Fired when a change is done: on release, and after every key.
`min` / `max`	`number`	`0` / `100`	The range.
`step`	`number \| null`	`1`	The step. `null` limits the value to `marks`.
`shiftStep`	`number`	`10`	PageUp, PageDown and Shift with an arrow.
`marks`	`boolean \| { value, label? }[]`	`false`	`true` marks every step; or the marks, each with the label it shows under it.
`orientation`	`'horizontal' \| 'vertical'`	`'horizontal'`	A vertical slider is `12rem` tall unless given a `height`.
`track`	`'normal' \| false \| 'inverted'`	`'normal'`	The line between the thumbs - `'inverted'` fills the rest, `false` draws none.
`scale`	`(value: number) => number`	itself	The value as it is shown and announced - not what is stored.
`valueLabel`	`'off' \| 'auto' \| 'on'`	`'off'`	When a thumb shows its value: never, while hovered or focused, or always.
`formatValueLabel`	`(value: number, index: number) => ReactNode`	the scaled value	What the label says.
`getAriaLabel`	`(index: number) => string`	-	Names each thumb. A range needs it unless a `FormLabel` names them; a single thumb may take `aria-label`.
`getAriaValueText`	`(value: number, index: number) => string`	-	The value's text for each thumb, where the number alone isn't clear.
`shouldSwapThumbs`	`boolean`	`true`	A thumb passes its neighbour, taking its place. Without it, it stops at its neighbour.
`size`	`keyof Theme['sizes']`	its `FormControl`'s, `'md'`	The thumb's size (`theme.icon`) and the rail's thickness.
`color`	`keyof Theme['palette']`	its `FormControl`'s, `'primary'`	The track's and the thumbs' color.
`disabled`	`boolean`	its `FormControl`'s	Dimmed; the inputs are off and the pointer does nothing.
`error`	`boolean`	its `FormControl`'s	The track and thumbs take the error color, and the inputs are `aria-invalid`.
`name`	`string`	-	What a form submits each thumb's value as - one entry for each thumb.
`id`	`string`	its `FormControl`'s	On the first thumb's input, which a `FormLabel` targets.
`aria-label`, `aria-labelledby`, ...			On each thumb's input.

It takes the styled-system space props, width, height, minWidth, maxWidth, minHeight, maxHeight, className and data-testid too.

Keys

Key	Does
ArrowUp, ArrowRight	Up by `step` (with Shift, by `shiftStep`). ArrowRight goes down right to left.
ArrowDown, ArrowLeft	Down by `step` (with Shift, by `shiftStep`). ArrowLeft goes up right to left.
PageUp, PageDown	Up and down by `shiftStep`.
Home, End	To `min` and `max`.

With step={null} the arrows and Page keys go to the next mark the way they point and stop at the last; Home and End go to the first and last mark. Each key tells onChangeCommitted, even at an end.

The pointer

A press sets the value under it - on the nearest thumb, the later one on a tie - and a drag follows the pointer, held by pointer capture even past the slider's box; touch drags a thumb, not the page. onChange is told only when the value changes, onChangeCommitted once on release. A release that never came - another element took it - ends the drag on the next move.

In a range, a thumb dragged past its neighbour swaps places with it, the values staying sorted (shouldSwapThumbs={false} stops it at its neighbour instead).

In a `FormControl`

Its FormLabel targets the first thumb and names every thumb (aria-labelledby), its FormHelperText describes them, and the field's size, color, error and disabled apply, an own prop winning.

<FormControl>
  <FormLabel>Volume</FormLabel>
  <RangeInput defaultValue={30} />
  <FormHelperText>Loud or quiet.</FormHelperText>
</FormControl>

A slider always has a value, so it takes no required.

Customization

theme.components.RangeInput styles the root, the rail, the track, each thumb, the marks and their markLabels, the valueLabel and each input. Its defaultProps set size, color, orientation, track, step, shiftStep, valueLabel and shouldSwapThumbs.

Source code

If this page does not answer your question, have a look at the implementation of the component for more detail.