Fields & selection

Slider

A controlled native range input for choosing a numeric value from a bounded continuum.

SliderSliderProps

Component workbench

Configure the production component, inspect it at responsive widths, copy synchronized JSX, and share the exact state from one workspace.

Notification volume50

Generated example

This JSX stays synchronized with the controls and uses only public package APIs.

tsx

'use client';

import { useState } from 'react';
import { Slider } from '@ai-created/ui';

export function Example() {
  const [value, setValue] = useState(50);

  return (
    <Slider
      label="Completion"
      value={value}
      onChange={setValue}
    />
  );
}

Import

tsx

import { Slider } from '@ai-created/ui';

Install from a reviewed release

Replace the version placeholder with the release tag your product has reviewed.

shell

npm install --install-links "git+https://github.com/TheMarco/ai-created-ui.git#vX.Y.Z"

Load semantic tokens

css

@import '@ai-created/ui/styles/tokens.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

Extend Tailwind

module.exports = {
  presets: [require('@ai-created/ui/tailwind-preset')],
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@ai-created/ui/src/**/*.{js,ts,jsx,tsx}',
  ],
};

Anatomy

Named regions define what belongs to the component, what remains optional, and where semantic responsibility lives.

Header row

Required

Persistent label and optional formatted output.

Label

Required

Accessible range name.

label

Value output

Optional

Optional formatted current value.

output

Track

Required

6px range with filled progress.

Thumb

Required

22px draggable value handle.

Construction and authoring

The Figma-equivalent asset model, auto-layout, resizing, properties, slots, content bounds, localization, and governance contract.

Asset kind

component

Design library name

Components/Forms/Slider

Maturity

stable

Last reviewed

2026-08-29

Canvas applicability

Publish value, disabled, and value-label properties with a number property for the thumb position.

Auto layout

Direction: vertical
Gap: 8px
Padding: 0px
Alignment: Stretch
Wrap: No wrap inside track

Resizing

Width: fill
Height: hug
Minimum width: 160px
Maximum width: Parent controlled
Minimum height: 44px including label and target
Maximum height: Content controlled
Overflow: visible

Exposed design properties

Property	Type	Default	Code mapping	Options or notes
ValueRequired	number	50	value	No additional constraint
Minimum	number	0	min	No additional constraint
Maximum	number	100	max	No additional constraint
Step	number	1	step	No additional constraint
Show value	boolean	true	showValue	No additional constraint
Disabled	boolean	false	disabled	No additional constraint
LabelRequired	text	Value	label	No additional constraint

Nested assets and slots

Label row

subcomponent / required

Label and optional formatted value.

Internal label/value elements

Range input

primitive / required

Native range control and focus target.

<input type="range">

Track and thumb

subcomponent / required

CSS-painted current value representation.

Internal range styling

Content limits

Label

One concise line

Overflow: Wrap only when required by localization.

The adjusted quantity should be immediately clear.

Displayed value

One short formatted number and unit

Overflow: Use compact localized formatting.

Long prose does not belong in the value slot.

Localization and RTL

Translatable: Label, Formatted value and unit

Document direction controls the track progression where platform conventions require it.
Use locale-aware number and unit formatting.
Test decimal separators.
Test long units.
Test minimum, maximum, and an invalid out-of-range input.

Responsive behavior

Track fills its form column.

No internal breakpoint

Keep at least 160px of usable track width.
Pair with direct numeric entry when precision is critical.

Authoring limits

Figma number properties demonstrate position but not keyboard increments.
min must be less than max, step must be positive, and value must remain within the range.

Accountable owner

Design systems form foundations owner

Canonical source: src/components/Slider.tsx

Range, formatting, or keyboard changes require input accessibility review.
A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.
The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change.

Read the system construction standard

Visual specification

These measurements and semantic tokens define the supported visual contract. Local overrides should preserve the same hierarchy and interaction cues.

Interaction row minimum height

44px

Track height

6px

Thumb

22 × 22px

Thumb border

2px

Label/track gap

8px

Hover thumb scale

1.15×

Rules

Always expose units through formatValue when the raw number is ambiguous.
Use a step appropriate to the precision users can perceive.
Provide direct numeric entry instead when exact values matter.

Token dependencies

--color-action-primary

Progress fill and thumb.

--color-surface2

Unfilled track.

--color-control-border

Track boundary.

--color-bg

Thumb border separation.

--color-focus

Range focus outline.

States and behavior

A component is not complete until its passive, interactive, disabled, and exceptional states remain understandable in both themes.

default

Trigger: Enabled range input.
Visual response: Action-color progress and thumb over surface track.
Behavior: Pointer drag and native key commands change by step.

disabled

Trigger: disabled is true.
Visual response: 50% opacity, no hover scale, not-allowed cursor.
Behavior: Focus and input are suppressed.

focus-visible

Trigger: Keyboard focus reaches the range.
Visual response: 2px focus outline with 3px offset.
Behavior: Arrow and page keys adjust value.

Accessibility contract

Semantics, accessible naming, keyboard behavior, focus and announcements are implementation requirements, not optional documentation.

Semantics: Native input[type=range] associated with a label and optional output.
Accessible name: Required label names the range.

Provide useful min, max, and step values.
aria-valuetext must match the visible formatted output.
Do not use color alone to communicate the value; thumb position and output remain available.

Keyboard behavior

Arrow Left / Down: Decreases by one step.
Arrow Right / Up: Increases by one step.
Home / End: Moves to minimum / maximum.
Page Up / Page Down: Changes by the browser-defined larger increment.

Implementation

Use the public package API and preserve the controlled-state, native-attribute, and ref contracts described below.

tsx

import { Slider } from '@ai-created/ui';

Server Component compatible

onChange receives a number, not an event.
Progress is clamped to 0-100%, including max equal to min.
formatValue drives both visible output and aria-valuetext.

tsx

<Slider label="Opacity" value={opacity} onChange={setOpacity} formatValue={(v) => `${v}%`} />

Public API

These props and helpers are compatibility contracts. Changes require migration guidance and release notes.

Prop	Type	Default	Contract
value	number	required	Controlled numeric value.
onChange	(value: number) => void	required	Called with the new value.
label	string	required	Accessible label.
min	number	0	Minimum value.
max	number	100	Maximum value.
step	number	1	Increment.
showValue	boolean	true	Shows formatted value.
formatValue	(value: number) => string	String(value)	Formats the displayed value.

Usage guidance

These rules keep the component recognizable across products without preventing deliberate composition.

Do

Use for values users understand spatially, such as volume or opacity.
Show the current value when precision is useful.

Do not

Do not use for unbounded values.
Do not hide value formatting when units are unclear.

Testing contract

The component should be verified as rendered UI, an interaction model, an accessibility surface, and a theme-aware visual artifact.

Unit

Computes and clamps progress; handles max equal to min.
Formats output and aria-valuetext consistently.

Interaction

Pointer and keyboard changes call onChange with numeric values within range.

Accessibility

Label, output htmlFor, range values, disabled state, and focus ring are valid.

Visual

Capture min/mid/max, focus, hover, disabled, hidden output, custom units, and themes.

Related specifications

field dropdown