Fluid Slider Component

A labeled Base UI range control with a dedicated draggable indicator and a surface that moves directly to any selected value.

Features

Drag the boundary indicator for precise, continuous adjustment.
Click anywhere on the surface to move directly forward or backward to that value.
Fixed label and trailing value keep the control readable throughout adjustment.
Base UI range semantics, keyboard controls, form integration, and value constraints.
Restrained rubber-band feedback at the minimum and maximum without changing the semantic value.
Optional reference marks, formatted values, and boundary handle.
Instant keyboard and reduced-motion updates with no decorative bounce.
Semantic --fluid-slider-* tokens for consumer theme customization.

Frequency

15%

Resonance

Playground

Change the initial value and label, then compare direct surface selection with precise indicator dragging.

Frequency

35%

Controls

Label

Initial value35

Show value

Show handle

Show marks

Installation

npx shadcn@latest add @sona-ui/fluid-slider

Usage


export default function FluidSliderDemo() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-5">
      <FluidSlider
        label="Frequency"
        defaultValue={15}
        formatValue={(value) => `${value}%`}
      />
      <FluidSlider
        label="Resonance"
        defaultValue={6}
        max={10}
        marks={[2, 4, 6, 8]}
      />
    </div>
  );
}

Props

Property	Type	Default	Description
`label`	`ReactNode`	`required`	Visible label associated with the slider.
`value`	`number`	`undefined`	Controlled slider value.
`defaultValue`	`number`	`50`	Initial value for uncontrolled usage.
`onValueChange`	`( value: number, details: Slider.Root.ChangeEventDetails, ) => void`	`undefined`	Called continuously while the value changes.
`onValueCommitted`	`( value: number, details: Slider.Root.CommitEventDetails, ) => void`	`undefined`	Called when a pointer or keyboard interaction commits.
`min`	`number`	`0`	Minimum allowed value.
`max`	`number`	`100`	Maximum allowed value.
`step`	`number`	`1`	Smallest value increment.
`largeStep`	`number`	`10`	Increment used by Page Up, Page Down, and modified arrow keys.
`marks`	`number[]`	`[]`	Numeric positions rendered as quiet reference marks.
`formatValue`	`(value: number) => string`	`undefined`	Formats the visible and accessible value text.
`format`	`Intl.NumberFormatOptions`	`undefined`	Intl options used when no custom formatter is supplied.
`locale`	`Intl.LocalesArgument`	`undefined`	Locale used by the default number formatter.
`showValue`	`boolean`	`true`	Whether the trailing formatted value is visible.
`showHandle`	`boolean`	`true`	Whether the active boundary grip is visible.
`disabled`	`boolean`	`false`	Whether the slider ignores user interaction.
`name`	`string`	`undefined`	Name submitted with the slider's hidden range input.
`form`	`string`	`undefined`	ID of the form that owns the slider input.
`ariaLabel`	`string`	`undefined`	Accessible name used instead of the visible label.
`className`	`string`	`undefined`	Additional classes for the slider root.
`trackClassName`	`string`	`undefined`	Additional classes for the track surface.
`surfaceClassName`	`string`	`undefined`	Additional classes for the filled surface.
`labelClassName`	`string`	`undefined`	Additional classes for the fixed label.
`valueClassName`	`string`	`undefined`	Additional classes for the trailing value.
`handleClassName`	`string`	`undefined`	Additional classes for the boundary grip.