Slider

Import

import { Slider } from '@envsemble/envui';

Usage

<Slider
  label="Opacity"
  defaultValue={80}
  formatValue={(value) => `${value}%`}
  onValueCommitted={save}
/>

Leave it uncontrolled, with defaultValue, the minimum by default, or control it with value and onValueChange, which receives the value as often as the handle moves. formatValue formats the value with its unit, as it shows at the end and is announced; without it, the number shows in the locale, EnvUIProvider's by default. description goes under it, and error says how to correct the value.

Saving

onValueCommitted reports the value once a change is complete: when the pointer is released or the track pressed, and after each key. Save from it.

Steps in a form

min and max, 0 and 100 by default, set the range, and step, 1 by default, the distance between values, counted from min. largeStep, a tenth of the range in whole steps by default, is the change of Page Up, Page Down and an arrow with Shift. name submits the value with a form, form names a form the slider sits outside of, and a reset returns to defaultValue.

Disabled

<Slider
  label="Storage per member"
  description="Sam Lee, your administrator, sets this limit for everyone at Northwind."
  min={5}
  max={100}
  step={5}
  defaultValue={20}
  formatValue={(value) => `${value} GB`}
  disabled
/>

Composition

ref reaches the native range input, which holds the value and takes focus, as a field's does, so a form library can register it; className, style and the other native props go to the root. The row of the label and the value is env-slider-header, its numbers of one width. The field, env-slider-control, is the track's quiet tint, which takes the pointer. The span the value moves along, env-slider-track, runs across the whole field, so the fill is empty at the minimum and full at the maximum, and draws the faint ticks at the steps, or at the large steps where the steps are many.

The field marks what it shows besides its text and fill:

data-handle while the handle shows, under a hovering or pressing pointer and with keyboard focus.
data-ruler while the ticks do, under a hovering or pressing pointer.
data-dragging while the pointer presses it and drags the value.
A release clears them until the pointer leaves and comes back.

Accessibility

You provide

A label, or aria-label on a slider without one.
A formatValue with the unit, in the application's language.
The effect of the value, and saving it.

envUI provides

A native range input in Base UI's slider, named by its label.
The formatted value as aria-valuetext, such as 40%.
The description linked to the input, a focus ring around the whole field, and the touch height on touch screens, where the whole field takes the finger.

Props

A value in a range, as a field: as tall as the fields and with their corners, so it sits in a form among them, with its label inside at the start, its value at the end and a fill from the start that shows it. Pressing or dragging anywhere in it chooses a value, and so do the arrow keys. At rest it shows only its text and fill; a thin handle at the value and faint ticks at its steps appear under the pointer and while it is pressed, and go once it is released, and the handle alone shows with keyboard focus. An optional description sits below it.

Prop	Type	Description
`label`required	`ReactNode`	The value's name, inside the slider at its start, such as Opacity. It names the slider.
`description`	`ReactNode`	Lasting guidance under the slider, such as what the value applies to, linked to the slider as its description.
`error`	`ReactNode`	A message under the slider that says how to correct the value; it joins the slider's description, after the description.
`value`	`number`	The value of a controlled slider; update it from onValueChange.
`defaultValue`Default `min`	`number`	The value an uncontrolled slider starts with; a native form reset returns to it.
`onValueChange`	`(value: number) => void`	Receives the value while it changes, by dragging, pressing the track or with the keyboard, as often as the thumb moves.
`onValueCommitted`	`(value: number) => void`	Receives the value once a change is complete: when the thumb is released or the track pressed, and after each key. Use it for work that runs once per change, such as saving.
`min`Default `0`	`number`	The lowest value, at the start of the track.
`max`Default `100`	`number`	The highest value, at the end of the track.
`step`Default `1`	`number`	The distance between the values the slider can take, counted from min; an arrow key moves by it.
`largeStep`Default `a tenth of the range in whole steps, at least one step`	`number`	The change of Page Up, Page Down and an arrow key with Shift.
`formatValue`	`(value: number) => string`	The value as people read it at the slider's end and assistive technology announces it, such as (value) => `${value}%`. Without it, the number shows in the locale.
`locale`	`string`	The locale of the shown number: EnvUIProvider's, else the browser's.
`disabled`Default `false`	`boolean`	Dim the slider; it can't be focused or moved, and forms leave it out.
`name`	`string`	Submits the value with a form under this name.
`form`	`string`	The id of a form the slider belongs to when it sits outside of it.
`ref`	`Ref<HTMLInputElement>`	The native range input, which holds the value and takes focus, as a field's ref reaches its input: for example to focus it, or for a form library to register it. className, style and the other native props go to the root.

Also accepts the native props of <div>, such as ref, className and aria-* attributes.

Part names

Each part's class and state attributes are public and versioned, for an application's CSS to style.

env-slider: The slider.
env-slider-control: The field: the track's tint, which takes the pointer.
env-slider-header: The row of the label and the value, over the track.
env-slider-indicator: The fill from the start to the value.
env-slider-label: The label, inside at the start.
env-slider-thumb: The handle: a thin line at the value, under the pointer and on focus.
env-slider-track: The span the value moves along, inside the rounded ends, with the ticks.
env-slider-value: The value as text.
data-disabled: Any value, or present
data-dragging: Present on env-slider-control
data-handle: Present on env-slider-control
data-ruler: Present on env-slider-control
data-ticks: Present

Color properties

Each sets a color of one instance, through style or CSS; its hover, focus and press follow it. They are public and versioned.

--env-slider-container: The track: the field's tint.
--env-slider-indicator: The fill that shows the value.
--env-slider-content: The label, the value, the handle and the ticks.

Changelog

1.0.0: onValueCommit is onValueCommitted, as Base UI names it, hint is description, and inputRef is ref, which reaches the native range input as a field's does, while the root takes className, style and the other native props. The value is formatted in EnvUIProvider's locale, or the one Slider takes. The row of the label and the value, env-slider-heading, is env-slider-header.

Sliders in the dark theme reach 3:1 contrast on every surface.
1.0.0-prerelease.6: A press on the track or a key moves the fill and the handle in --env-motion-duration-fast with --env-motion-ease-enter, so they agree with the value from the first frames, and a pressed handle, data-dragging on env-slider-control, grows a little.

Colors under the pointer and while pressed change with --env-motion-ease-enter, rather than easing in slowly, so hover and press show from the first frame.

A press on the track or a key glides the fill and the handle to the value, and a drag past the ends eases back without overshooting.
1.0.0-prerelease.5: error, as on a field.
1.0.0-prerelease.2: Slider is a field: as tall as the fields and with their corners, its label inside at the start, its value at the end in the text style of a field, with numbers of one width and a fill from the start, with a thin handle and faint ticks under the pointer and on focus, both fading where they pass under the text. The track has no outline. --env-slider-indicator colors the fill alone, and --env-slider-content the label, value, handle and ticks.