Slider

A draggable control for selecting a numeric value or range within defined bounds. Supports single value and range selection, tick marks, custom value formatting, and vertical orientation. Use it when users need to explore a continuous range, such as volume, price, or percentage.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

Slider

Prop	Type	Default	Description
label *	string		Label text (always rendered for accessibility).
value *	number \| [number, number]		Current value: a `number` for single thumb mode or `[number, number]` for range mode.
onChange	(value: number) => void \| (value: [number, number]) => void		Callback fired on value change during drag.
onChangeEnd	(value: number) => void \| (value: [number, number]) => void		Callback fired when drag ends.
min	number	0	Minimum value.
max	number	100	Maximum value.
step	number	1	Step increment.
orientation	'horizontal' \| 'vertical'	'horizontal'	Orientation of the slider.
formatValue	(value: number) => string		Custom value formatting function used for display and `aria-valuetext`.
valueDisplay	'tooltip' \| 'text' \| 'none'	'tooltip'	How the current value is displayed.
marks	Array<{ value: number; label?: string }>		Tick marks at specified positions with optional labels. Unfilled marks use the track color; marks inside the filled region (at or behind the thumb, or between the thumbs in range mode) use the fill color.
minStepsBetweenThumbs	number	0	Minimum number of steps between thumbs in range mode; prevents thumbs from overlapping.
isDisabled	boolean	false	Whether the slider is disabled.
htmlName	string		The HTML name attribute for form submissions. Renders hidden inputs carrying the current value (two entries in range mode).
disabledMessage	string		Explains why the slider is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the thumb focusable via aria-disabled (value changes stay blocked). Use this instead of wrapping a disabled Slider in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.
isOptional	boolean	false	Whether the field is optional.
isRequired	boolean	false	Whether the field is required.
isLabelHidden	boolean	false	Whether to visually hide the label.
description	string		Description text rendered below the label.
status	{type: 'warning' \| 'error' \| 'success', message?: string}		Status indicator object (`{ type, message }`) for validation feedback.
labelTooltip	string		Tooltip text for an info icon displayed next to the label.
width	SizeValue		Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.
containerXstyle	StyleXStyles		StyleX styles for the field container (label, control, and status together). No effect inside InputGroup (style the InputGroup instead) or in a `horizontal-labels` FormLayout. Root `xstyle`, `className`, and `style` are not accepted.
containerClassName	string		Class name for the field container. Same targeting as `containerXstyle`.
containerStyle	CSSProperties		Inline styles for the field container. Same targeting as `containerXstyle`.
controlXstyle	StyleXStyles		StyleX styles for the visual control box: the element that paints the border and background and holds icons and end controls. Never the native input.
controlClassName	string		Class name for the visual control box.
controlStyle	CSSProperties		Inline styles for the visual control box.

Usage guidance

Always provide a label, even if visually hidden, so the slider is accessible to screen readers.
Format values with meaningful units like "$50" or "75%" instead of raw numbers.
Avoid: Use for precise numeric entry; pair with a text input or use NumberInput instead.
Avoid: Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.
Avoid: Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

Theming API

{
  "targets": [
    {
      "className": "astryx-slider",
      "visualProps": [
        "orientation"
      ],
      "states": [
        "disabled"
      ]
    },
    {
      "className": "astryx-slider-control",
      "visualProps": [
        "orientation"
      ],
      "states": [
        "disabled"
      ]
    },
    {
      "className": "astryx-slider-track",
      "visualProps": [
        "orientation"
      ]
    },
    {
      "className": "astryx-slider-thumb",
      "visualProps": [
        "orientation"
      ],
      "states": [
        "disabled"
      ]
    }
  ]
}

Accessibility

Thumb: The thumb must have at least 3:1 contrast with the track and the surface behind it. Pointer down is the whole drag: measure the thumb with the pressed overlay applied. — 3:1

Anatomy

Label: Text identifying the numeric setting controlled by the slider.
Description: Helper text between the label and the slider control.
Slider: Control row containing the track, thumb or thumbs, and optional text value.
Interactive control: Pointer and keyboard interaction surface containing the rail, fill, marks, and thumbs.
Track: Background rail representing the available numeric range.
Filled range: Accent segment from the minimum to a single value, or between two range values.
Tick mark: Position marker supplied through the marks collection.
Mark label: Optional text displayed beside a tick mark.
Thumb: Draggable value indicator; range mode renders a minimum and maximum thumb.
Value display: Formatted current value shown beside the slider when valueDisplay is text.
Value tooltip: Formatted current value shown in a tooltip when valueDisplay is tooltip.
Status message: Error, warning, or success message below the slider.

Examples

Slider: A slider control set to 50%.
Slider — Formatted Value: Slider with custom formatting showing temperature in Fahrenheit.
Slider — Range: Range slider for selecting a value range like price bounds.
Slider — With Marks: Slider with labeled tick marks at fixed intervals.
Slider — Validation States: Sliders with error, warning, and success validation states.