Circular Slider for Ark UI

The thumb sits on a ring, and the current number sits in the center.

Use it for a hue, a heading, or anything people set by turning. A linear range still belongs on a Slider. In React, Ark UI reports an angle from 0 to 360, which you scale if the setting is a percent.

Installation

Anatomy

CircularSlider
├── CircularSliderLabel
├── CircularSliderThumb
├── CircularSliderValue
├── CircularSliderContext
├── CircularSliderTrack
└── CircularSliderMarker
    └── CircularSliderMarkerGroup

Usage

import {
  CircularSlider, CircularSliderValue,
} from "@/components/ui/circular-slider";

<CircularSlider aria-label="Angle" defaultValue={45}>
  <CircularSliderValue suffix="°" />
</CircularSlider>

Accessibility

Demos

Context

The number in the middle does not have to be the angle with a unit glued on. CircularSliderContext hands you the live value, so the center can show a mapped range or a unit you format yourself. CircularSliderValue with suffix is the shorter path when the angle itself is the label. Use context when that label is a calculation.

Controlled

The degrees under the ring are the same state the dial is controlled with. Keep the angle yourself when a caption, a reset, or a save handler has to read it. Pass value back on every change, and use defaultValue when nothing else needs the number until the form submits. The ring will not invent a second copy of the state.

Custom Markers

markers can be a list of angles instead of a clock face. These four are the cardinal directions, which is what a compass or a quarter-turn control actually means. The thumb still moves by step between the ticks. Pass true when a regular clock is enough, and pass the list when only a few marks are real.

Disabled

disabled freezes the thumb and fades the ring. The angle stays visible, which is what you want when a preset owns the value or the control is not unlocked yet. Do not use it as the error state. A value the user still has to correct stays enabled and uses invalid instead.

Invalid

invalid switches the ring to the error treatment so a failed check is visible on the control, not only in a toast somewhere else. It does not explain itself. Keep a text message in the form. Turn it on after validation, for example when a required angle was never moved, and leave it off for a value that is merely unusual.

Read Only

readOnly leaves the angle on screen and in the form, but the user cannot change it. That fits a confirmed setting people should still be able to inspect, or a value copied from somewhere else. Prefer disabled when the control should drop out of the way of the rest of the form entirely. Read-only is for looking, not for locking the page.

Root Provider

The ring does not have to own its state. useCircularSlider creates the angle, a button outside calls setValue, and CircularSliderRootProvider shares that state with the readout. Use this when a preset or a neighboring control must move the dial without living inside it. A controlled value is less machinery when only one component needs the number.

Size

size is the diameter in pixels. 180 is nearly twice the default of 100, which is what you want when the dial is the main control, a volume knob or a compass, and not a small field in a form. The thumb and the track scale with it. For a heavier stroke without a larger ring, change thickness instead.

Step

step is 60 degrees here, so the thumb jumps between coarse stops instead of every degree. markers together with markersAtSteps puts a tick on each of those stops, and the ticks follow if you change step. Use that pairing when the angle is a clock hour or another coarse choice. Leave step at 1 when people need a precise angle.

Thickness

thickness is the stroke of the track, in pixels. 14 is a heavy ring against the default of 6, useful when the dial is small and a thin track would disappear, or when the fill itself is what people watch. The diameter stays whatever size is. Change size when the whole control should grow, not just the stroke.

With Label

CircularSliderLabel names the dial, here as hue, and that name is what a screen reader announces. Use it whenever the ring is not sitting next to another caption. aria-label on the root is the alternative when you do not want the word drawn on the control. A color tool usually wants the visible word.

With Markers

markers set to true draws clock ticks every 60 degrees, without you listing angles. Use that for a full turn where people need a sense of position, a timer or a heading, and the ticks are orientation rather than values. Pass a list of angles when only a few marks mean something. The thumb does not snap to the ticks unless step says so.

With Value

The center can hold more than digits. prefix takes an icon and suffix takes the unit, on a slightly larger and thicker ring, which reads as a thermostat. The icon is decorative, because the number and the unit already say what the control is. Use prefix and suffix before reaching for context, unless the text in the middle is a calculation.

FAQ

API Reference