CircularSlider

Playground

Installation

npx shadcn@latest add https://tessinaui.com/r/circular-slider.json

Usage

import { CircularSlider } from "@tessinaui/ui";

<CircularSlider
  label="Brightness"
  value={value}
  onValueChange={(v) => setValue(v as number)}
  formatValue={(v) => `${v}%`}
>
  <span>{value}%</span>
</CircularSlider>

When to use it

A ring, not a bar, when the value is cyclical or has no natural end — a time of day, a compass heading, a hue — or when the control has to sit inside a round read-out, which is what every sleep, thermostat and dimmer screen in the research does. For a plain bounded quantity in a form, use Slider: a straight track is easier to aim at and reads faster.

It is a separate component rather than a slider variant because the interaction model differs, not just the paint. A linear slider maps one axis to a value; this maps an angle, and on a wrapping scale the shorter way between two values can be through the end of the range.

Examples

Default

A single handle with a centre read-out.

Sleep range

Two handles on a wrapping 24-hour scale. Bedtime after wake-up is the normal way to say "overnight", so the arc runs forward through midnight rather than backwards around the dial. Each handle carries its own name — "Sleep, 22:00 to 06:00" on one control does not tell a screen-reader user which end is about to move.

Gauge

An open arc: sweep={270} with startAngle={225}, the shape thermostats use. wrap is ignored when the arc has a gap — there is no seam to travel through, and silently teleporting a handle across it would be worse than clamping.

Accessibility

• Every handle is a role="slider" with aria-valuemin / aria-valuemax / aria-valuenow, focusable in source order.
• Pass formatValue. A bare 22 on a clock face means nothing; it becomes aria-valuetext="22:00".
• A range takes two labels, one per handle.
• Keyboard: arrows step, Shift+arrow and PageUp/PageDown take the large step, Home/End jump to the ends. On a wrapping scale the arrows carry through the seam.
• The SVG ring is aria-hidden and focusable="false" — the handles carry all the semantics, so assistive tech never meets a nameless graphic.
• Handles keep a 44px touch target on phones via an invisible centred pad, so the visible handle can stay proportionate to a small ring (WCAG 2.5.5).
• readOnly keeps focus and announces aria-readonly; disabled removes the handles from the tab order.

API Reference

CircularSlider

Sizes:

CircularSliderSkeleton

Placeholder ring. Its box comes from the component's own diameter map, so the two cannot drift.