Slider
Slider chooses one numeric value within a known bounded range through keyboard, pointer, or touch input.
Overview and decision boundary
Use Slider to choose one numeric value within a known bounded range.
Do not use Slider for exact text entry when Input is clearer.
Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm exec nerio add sliderimport { Slider } from "@nerio-ui/ui/client";Usage
import { Slider } from "@nerio-ui/ui/client";<Slider label="Tip amount" name="tipAmount" min={0} max={50} defaultValue={15} valueLabel="$15" getAriaValueText={(_, value) => `${value} US dollars`}/>Variants
| Orientation | Description |
|---|---|
Horizontal | Default fluid inline-axis control. |
Vertical | Bounded block-axis control with the same single-value API. |
Anatomy
| Slot | Description |
|---|---|
root | Single-value Base UI Slider state and form owner. |
header | Optional visible label and consumer-formatted value row. |
label | Visible accessible name associated with the nested range input. |
value | Optional visible valueLabel supplied by the consumer. |
control | Pointer and touch interaction surface. |
track | Neutral full numeric range. |
indicator | Accent fill from min to the current value. |
thumb | One draggable handle containing the native range input. |
description | Optional supporting text connected through aria-describedby. |
States
| State | Behavior |
|---|---|
Default | Uncontrolled value defaults to min when defaultValue is omitted. |
Focus | The thumb keeps the system focus-visible ring. |
Dragging | Pointer and touch update one value through Base UI. |
Disabled | Prevents interaction and excludes the control from form submission. |
Read-only | Remains focusable and form-associated while canceling value changes. |
Invalid | Exposes aria-invalid and data-invalid without owning validation policy. |
Required | Preserves native range required metadata; a range always has a value. |
Motion
- Track and thumb feedback use shared hover duration and easing tokens.
- Value changes remain immediate; reduced motion removes nonessential transition duration.
Accessibility
- Uses the Base UI Slider primitive for keyboard, pointer, touch, form, and orientation behavior.
- Requires exactly one accessible name through a visible label, aria-label, or aria-labelledby.
- Supports Arrow keys, Home, End, Page Up, and Page Down through the nested native range input.
- Supports value, defaultValue, onValueChange, onValueCommitted, min, max, step, largeStep, name, form, disabled, readOnly, and required while intentionally rejecting arrays and multiple thumbs.
- Use format and locale for number formatting, and aria-valuetext or getAriaValueText for localized semantic value text.
- Pair the document dir attribute with Base UI DirectionProvider so horizontal keyboard and pointer behavior follows LTR or RTL.
- Read-only Slider remains focusable and form-associated while canceling value changes.
- Consumers own units, marks, thresholds, tooltips, charts, filters, media logic, and product-specific scales.
Review the shared responsibility and evidence boundaries in the Accessibility foundation alongside this component-specific contract. Use the Spacing & layout foundation for shared density, wrapping, overflow, reflow, and component-versus-product ownership guidance. The Color foundation, Typography foundation, and Localization foundation define the shared visual-role, text-resilience, direction, and locale boundaries used by component examples.
API
| Prop | Type | Description |
|---|---|---|
value / defaultValue | number | Controlled or uncontrolled single numeric value. |
onValueChange / onValueCommitted | (value, details) => void | Continuous and committed updates with Nerio reason and native event details. |
min / max / step / largeStep | number | Bounds, Arrow-key step, and Page-key step. |
orientation | horizontal | vertical | Changes layout and native aria-orientation. |
label | ReactNode | Visible accessible naming strategy. |
aria-label / aria-labelledby | string | Naming alternatives when label is omitted. |
valueLabel | ReactNode | Optional visible value formatted by the consumer. |
format / locale | Intl options | Formats the Base UI numeric value without embedding product units in Core. |
aria-valuetext / getAriaValueText | string / function | Localized semantic value text for assistive technology. |
name / form / required / disabled / readOnly | form props | Native form ownership and availability behavior. |
ref / inputRef | refs | Accesses the root div or nested native range input. |
Implementation contract
| Contract | Value |
|---|---|
Base UI | Slider Root, Control, Track, Indicator, and one Thumb. |
Entrypoint | @nerio-ui/ui/client |
Registry | nerio add slider installs the component, merge/ref utilities, token bridge, and tokens. |
Boundary | One value and one thumb; product scale meaning remains consumer-owned. |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Use Slider to choose one numeric value within a known bounded range.
Do / do not
Do
- Use Slider for one approximate or continuously adjustable bounded value.
- Show units outside the primitive and localize accessible value text.
- Use Input when exact numeric entry is more important than direct manipulation.
Do not
- Add multiple thumbs or range selection to Core Slider.
- Embed marks, tooltips, charts, pricing, filtering, or media policy.
- Use color alone to explain the current value or its meaning.
Related components
Tokens
| Group | Tokens | Controls |
|---|---|---|
Dimensions | --n-slider-control-size / length / track-size / thumb-size | Hit area and orientation geometry. |
Track | --n-slider-track-* / --n-slider-indicator-background | Neutral range and accent value fill. |
Thumb | --n-slider-thumb-* / --n-slider-focus-ring | Invariant white handle surface with tokenized boundary, elevation, and focus. |
Spacing | --n-slider-gap | Compact rhythm between header, control, and description. |
Disabled | --n-slider-disabled-* | Muted track, indicator, thumb, and opacity. |
Motion | --n-slider-duration / --n-slider-easing | Tokenized state feedback with reduced-motion support. |