"use client"; import * as React from "react"; import { mergeProps } from "@base-ui/react/merge-props"; import { useRender } from "@base-ui/react/use-render"; import { cn } from "@/lib/utils"; import { useControllableState } from "@/registry/default/hooks/use-controllable-state"; import { angleToProgress, angleToUnclampedProgress, angularDistance, arcStroke, clamp, continueDrag, createDial, easeOutExpoTimeAt, getActiveSpan, isInSpan, mod, pickOverlappedThumb, pointToAngle, ringHeight, trimOriginCap, progressToAngle, progressToValue, round, snapValue, tickProgresses, valueToProgress, widenSpan, wrapDelta, placeRangeThumb, type CircularSliderDirection, type Dial, type Span, type ThumbCollision, } from "./lib/geometry"; /** Duration of a value change that animates (click, Home/End/Page, external). */ const SETTLE_MS = 350; /** Gap between a knob face and the tick band around it, in px. */ const KNOB_GAP = 6; /** Pixels of vertical drag that cover the whole sweep in `dragMode="vertical"`. */ const VERTICAL_DRAG_PX = 200; export type CircularSliderChangeReason = "drag" | "click" | "keyboard"; export interface CircularSliderChangeDetails { reason: CircularSliderChangeReason; /** Index of the thumb that moved; `-1` when a range span moved as a whole. */ activeThumbIndex: number; } type SliderValue = number | readonly number[]; interface CircularSliderContextValue { dial: Dial; values: readonly number[]; /** * Where the thumbs are drawn: between steps during a smooth drag, else the * values. The arc, thumbs, ticks and knob face follow this; text and * screen readers read `values`. */ shown: readonly number[]; /** Values before the latest change, for timing the tick sweep. */ previousValues: readonly number[]; origin: number; size: number; thickness: number; /** How far the band sits in from the edge, making room for a pill thumb. */ inset: number; thumbShape: "bead" | "pill"; variant: "ring" | "knob"; pressed: boolean; dragging: boolean; activeIndex: number; /** The thumb the pointer holds; null when idle or dragging a span. */ heldIndex: number | null; /** The thumb a press under the mouse would hold. */ hoverIndex: number | null; focusVisibleIndex: number | null; /** The latest change lands without a transition. */ instant: boolean; formatValue?: (value: number, index: number) => string; } const CircularSliderContext = React.createContext(null); function useCircularSliderContext(): CircularSliderContextValue { const context = React.useContext(CircularSliderContext); if (!context) { throw new Error( "CircularSlider parts must be rendered inside .", ); } return context; } function toArray(value: SliderValue): readonly number[] { return typeof value === "number" ? [value] : value; } function sameValues(a: readonly number[], b: readonly number[]): boolean { return a.length === b.length && a.every((v, i) => v === b[i]); } /** Thumb nearest a screen angle; ties go to the last one moved. */ function nearestThumb( dial: Dial, values: readonly number[], angle: number, preferred: number, ): number { let best = preferred; let bestDistance = Infinity; values.forEach((value, index) => { const distance = angularDistance( progressToAngle(dial, valueToProgress(dial, value)), angle, ); if ( distance < bestDistance - 0.001 || (Math.abs(distance - bestDistance) <= 0.001 && index === preferred) ) { best = index; bestDistance = distance; } }); return best; } /** Radial slop, in px, a press may land outside the band and still count. */ const BAND_SLOP = 8; /** Pointer travel, in px of arc, that settles which overlapped thumb is held. */ const PICK_TRAVEL = 4; /** Share of a knob's radius around its center where drags are ignored. */ const KNOB_DEAD_ZONE = 0.15; /** * Pointer travel, in px, before a press counts as a drag. Below it a click's * small wobble neither moves the value nor cuts the click's sweep short. */ const DRAG_THRESHOLD = 3; interface PointerGeometry { angle: number; distance: number; /** Rendered px per authored px, for a root resized with CSS. */ scale: number; /** Radius of the band's center line, in screen px. */ bandRadius: number; /** Degrees of arc a thumb answers to either side of its center. */ grabDegrees: number; } /** * Where a pointer sits relative to the dial. Press and hover both read this, * so what a hover marks as grabbable is exactly what a press grabs. */ function measurePointer( event: React.PointerEvent, size: number, thickness: number, inset: number, ): PointerGeometry { const rect = event.currentTarget.getBoundingClientRect(); const scale = rect.width / size; const cx = rect.left + rect.width / 2; // The dial is the square at the top of the root (a half dial is shorter). const cy = rect.top + rect.width / 2; const bandRadiusPx = rect.width / 2 - (inset + thickness / 2) * scale || 1; return { angle: pointToAngle(event.clientX, event.clientY, cx, cy), distance: Math.hypot(event.clientX - cx, event.clientY - cy), scale, bandRadius: bandRadiusPx, grabDegrees: ((thickness * scale * 0.75 + 8 * scale) / bandRadiusPx) * (180 / Math.PI), }; } function slopDegrees(px: number, radius: number): number { return ((px / radius) * 180) / Math.PI; } /** On a ring's band, give or take the slop, and inside a partial sweep. */ function isOnBand( g: PointerGeometry, dial: Dial, size: number, thickness: number, inset: number, ): boolean { const outer = (size / 2) * g.scale; const slop = BAND_SLOP * g.scale; const bandInner = outer - (inset + thickness) * g.scale; if (g.distance < bandInner - slop || g.distance > outer + slop) return false; if (dial.wrap || dial.sweep >= 360) return true; const p = angleToUnclampedProgress(dial, g.angle); const edge = slopDegrees((thickness * g.scale) / 2 + slop, g.bandRadius); return p >= -edge && p <= dial.sweep + edge; } /** * What a press on a ring's band takes hold of. Press and hover both ask, so * the thumb that grows under the mouse is the one a press would hold. */ function ringPressTarget( dial: Dial, values: readonly number[], g: PointerGeometry, index: number, origin: number, ): "pending" | "thumb" | "span" | "band" { const near = (v: number) => angularDistance(progressToAngle(dial, valueToProgress(dial, v)), g.angle) <= g.grabDegrees; // Overlapping thumbs wait for the first clear move to pick one. if (values.filter(near).length > 1) return "pending"; if (near(values[index])) return "thumb"; if ( values.length > 1 && isInSpan( dial, angleToProgress(dial, g.angle), getActiveSpan(dial, values, origin), ) ) { return "span"; } return "band"; } /** * A short move across a wrapping dial's seam (359° to 0°), which a transition * would spin nearly a full turn the wrong way. A large jump still sweeps. */ function crossesSeam( dial: Dial, from: readonly number[], to: readonly number[], ): boolean { return ( dial.wrap && from.length === to.length && from.some((value, i) => { const a = valueToProgress(dial, value); const b = valueToProgress(dial, to[i]); return Math.abs(b - a) > 180 && Math.abs(wrapDelta(a, b, 360)) < 90; }) ); } interface DragBase { pointerId: number; /** A value changed during the gesture, so release commits. */ changed: boolean; /** Where the press landed, for the drag threshold. */ downX: number; downY: number; /** Past the drag threshold. */ moved: boolean; /** Where a smooth drag last drew the thumbs. */ drawn?: number[]; } /** Holding one thumb; it follows the pointer at the offset it was grabbed. */ interface ThumbDrag extends DragBase { mode: "thumb"; index: number; /** Raw pointer progress at the last sample. */ lastPointer: number; grabOffset: number; } /** Pressed where a range's thumbs overlap; the first clear move picks one. */ interface PendingDrag extends DragBase { mode: "pending"; downPointer: number; bandRadius: number; } /** Holding a range's filled span; both ends shift together. */ interface SpanDrag extends DragBase { mode: "span"; lastPointer: number; /** Thumb progresses when the drag began; the shift is measured from these. */ start: number[]; shift: number; } /** Turning a knob, or dragging up and down in `dragMode="vertical"`. */ interface TurnDrag extends DragBase { mode: "knob" | "vertical"; index: number; /** Progress the gesture has accumulated, unsnapped. */ progress: number; lastAngle: number; lastY: number; } type DragState = ThumbDrag | PendingDrag | SpanDrag | TurnDrag; export interface CircularSliderRootProps< Value extends SliderValue = number, > extends Omit< useRender.ComponentProps<"div">, "defaultValue" | "onChange" | "dir" > { /** Controlled value. Pass an array of two numbers for a range. */ value?: Value; /** Uncontrolled initial value. Pass an array of two numbers for a range. */ defaultValue?: Value; onValueChange?: (value: Value, details: CircularSliderChangeDetails) => void; /** Fires when an interaction ends: pointer release or a keyboard step. */ onValueCommitted?: (value: Value) => void; min?: number; max?: number; step?: number; /** Step for Page Up / Page Down and Shift + arrow keys. */ largeStep?: number; /** Arc length of the dial in degrees, from 1 to 360. */ sweep?: number; /** * Screen angle of `min`, in degrees clockwise from 12 o'clock. Defaults to * centering the sweep on the top so a partial dial's gap sits at the bottom. */ startAngle?: number; direction?: CircularSliderDirection; /** * On a full circle, let values loop past `max` back to `min` (angles, * hours). Max and min then share a position. */ wrap?: boolean; /** * Where the indicator grows from. Defaults to `min`; set it to a midpoint * for a bipolar control, or to a live reading to show the distance to a * target. Ignored by ranges. */ origin?: number; /** Diameter in px. */ size?: number; /** Width in px of the outer band: the ring's stroke or the knob's ticks. */ thickness?: number; /** * `ring` is a stroke you grab anywhere along. `knob` is a raised face you * turn: grabbing it never jumps the value. */ variant?: "ring" | "knob"; /** * Color of the filled arc, thumb and active ticks: the selection-control * grey (`neutral`) or the brand fill (`primary`). */ color?: "neutral" | "primary"; /** * `angular` follows the pointer around the center. `vertical` turns the * value with up and down drags, like an audio knob. */ dragMode?: "angular" | "vertical"; /** * During a drag the thumb follows the pointer between steps and settles * onto the nearest one on release. Off, it moves in steps, like a notched * knob. Defaults to on for a ring dragged around the dial, off for a knob * or a vertical drag. */ smooth?: boolean; disabled?: boolean; name?: string; form?: string; /** * On a ring, `bead` sits inside the band and `pill` is a slim handle that * overhangs it (the band moves in, so the dial keeps its size). On a knob * it is the face's marker: a dot or a line. Defaults to `bead` on a ring * and `pill` on a knob. */ thumbShape?: "bead" | "pill"; /** Least distance, in steps, between a range's thumbs. */ minStepsBetweenValues?: number; /** * What a range thumb does when it runs into the other: `push` carries the * other along, `none` stops it there. */ thumbCollisionBehavior?: ThumbCollision; /** * Formats each value for display, e.g. `(v) => \`${v}°\``. Read by * `CircularSliderValue`, and spoken by screen readers unless * `getAriaValueText` says otherwise. */ formatValue?: (value: number, index: number) => string; /** * Accessible name for each thumb of a range. Defaults to "Start" and * "End", with `aria-label` naming the range as a whole. */ getAriaLabel?: (index: number) => string; /** Spoken value for a thumb. Defaults to `formatValue`. */ getAriaValueText?: (value: number, index: number) => string; } function CircularSliderRoot({ className, render, style, children, value: valueProp, defaultValue, onValueChange, onValueCommitted, min = 0, max = 100, step = 1, largeStep = 10, sweep = 270, startAngle, direction = "clockwise", wrap = false, origin: originProp, size = 144, thickness: thicknessProp = 12, variant = "ring", color = "neutral", dragMode = "angular", smooth: smoothProp, disabled = false, name, form, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledby, "aria-describedby": ariaDescribedby, formatValue, getAriaLabel, getAriaValueText, thumbShape: thumbShapeProp, minStepsBetweenValues = 0, thumbCollisionBehavior = "push", ...props }: CircularSliderRootProps) { // Past about 30% of the diameter a band stops reading as a ring and the // middle closes into a disc, so cap it there. const thickness = Math.min(thicknessProp, size * 0.3); const thumbShape = thumbShapeProp ?? (variant === "knob" ? "pill" : "bead"); const dial = React.useMemo( () => createDial({ min, max, step, sweep, startAngle, direction, wrap }), [min, max, step, sweep, startAngle, direction, wrap], ); const [rawValue, setRawValue] = useControllableState({ value: valueProp, defaultValue: defaultValue ?? min, }); // Clamped (or folded, when wrapping) and snapped once, so the text, arc, // hidden input and screen reader all agree, as with a native input. const values = toArray(rawValue).map((v) => snapValue(dial, v)); const isRange = typeof rawValue !== "number"; const origin = clamp(originProp ?? min, min, max); const inset = variant === "ring" && thumbShape === "pill" ? pillOverhang(thickness) : 0; const height = variant === "ring" ? ringHeight(dial, size, thickness, inset) : size; const thumbGap = Math.max(0, minStepsBetweenValues) * step; const spokenValue = getAriaValueText ?? formatValue; // Latest values for event handlers, which outlive the render they came from. const valuesRef = React.useRef(values); React.useEffect(() => { valuesRef.current = values; }); // Held arrow keys repeat fast, so those steps land instantly instead of // trailing the value. Keyed by the values they produced and cleared by any // other change, so later changes still animate. const [instantKey, setInstantKey] = React.useState(null); // What a press under the mouse would hold rather than jump: a thumb, by // index, or a range's filled span. const [hover, setHover] = React.useState(null); // Values before the latest change, for the tick sweep. Stored during render // ("previous props" pattern) so a change's first frame knows its origin. const valuesKey = values.join(","); const [history, setHistory] = React.useState({ key: valuesKey, previous: values, current: values, }); if (history.key !== valuesKey) { setHistory({ key: valuesKey, previous: history.current, current: values }); if (instantKey !== valuesKey) setInstantKey(null); // A thumb may have moved out from under a still mouse; the next move, or // a release, marks it again. setHover(null); } // A step across a wrapping dial's seam lands without a transition. const instant = crossesSeam(dial, history.previous, values) || instantKey === valuesKey; const smooth = smoothProp ?? (variant === "ring" && dragMode === "angular"); // Where a smooth drag draws the thumbs, between steps. const [drawn, setDrawn] = React.useState(null); // A drawn thumb shows only while its step is the accepted value; one a // controlled parent refused sits on what it accepted instead. const shown = drawn?.length === values.length ? drawn.map((v, i) => (snapValue(dial, v) === values[i] ? v : values[i])) : values; // What the pointer holds: a thumb, or a range's filled span, which moves // both ends and so marks neither as held. const [pressed, setPressed] = React.useState<"thumb" | "span" | false>(false); const [dragging, setDragging] = React.useState(false); const [activeIndex, setActiveIndex] = React.useState(0); const [focusVisibleIndex, setFocusVisibleIndex] = React.useState< number | null >(null); const inputRefs = React.useRef<(HTMLInputElement | null)[]>([]); const dragRef = React.useRef(null); // `:focus-visible` always matches a focused range input, so pointer-driven // focus is told apart by hand: set before the pointer focuses the input, // consumed by its focus handler. const focusFromPointer = React.useRef(false); // Focus a thumb after a pointer press so arrow keys work. The flag is only // set when a focus event will fire (an already-focused input fires none). const focusThumbInput = React.useCallback((index: number) => { const input = inputRefs.current[index]; if (!input || document.activeElement === input) return; focusFromPointer.current = true; input.focus({ preventScroll: true }); }, []); const emit = React.useCallback( (next: readonly number[]): Value => (isRange ? next : next[0]) as unknown as Value, [isRange], ); const commitValues = React.useCallback( (next: number[], details: CircularSliderChangeDetails): boolean => { if (sameValues(next, valuesRef.current)) return false; valuesRef.current = next; setRawValue(isRange ? next : next[0]); onValueChange?.(emit(next), details); return true; }, [isRange, setRawValue, onValueChange, emit], ); // Pointer, keyboard and assistive tech all move thumbs through here. const moveThumb = React.useCallback( ( index: number, candidate: number, reason: CircularSliderChangeReason, ): number[] => { const next = placeRangeThumb( dial, valuesRef.current, index, snapValue(dial, candidate), thumbGap, thumbCollisionBehavior, ); commitValues(next, { reason, activeThumbIndex: index }); return next; }, [dial, thumbGap, thumbCollisionBehavior, commitValues], ); const handlePointerDown = React.useCallback( (event: React.PointerEvent) => { if (disabled || event.button !== 0) return; const root = event.currentTarget; const g = measurePointer(event, size, thickness, inset); if (variant === "ring") { // A ring only answers along its band, so whatever sits in the middle // stays clickable, and not in the gap of a partial sweep. if (!isOnBand(g, dial, size, thickness, inset)) return; } else if (g.distance > (size / 2 + BAND_SLOP) * g.scale) { return; } const current = valuesRef.current; const pointer = angleToProgress(dial, g.angle); const index = current.length > 1 ? nearestThumb(dial, current, g.angle, activeIndex) : 0; const thumbProgress = valueToProgress(dial, current[index]); const base = { pointerId: event.pointerId, changed: false, downX: event.clientX, downY: event.clientY, moved: false, }; let drag: DragState; if (dragMode === "vertical" || variant === "knob") { drag = { ...base, mode: dragMode === "vertical" ? "vertical" : "knob", index, progress: thumbProgress, lastAngle: g.angle, lastY: event.clientY, }; } else { const target = ringPressTarget(dial, current, g, index, origin); if (target === "pending") { drag = { ...base, mode: "pending", downPointer: pointer, bandRadius: g.bandRadius, }; } else if (target === "thumb") { // Grabbing the thumb itself holds on without moving it. drag = { ...base, mode: "thumb", index, lastPointer: pointer, grabOffset: dial.wrap ? wrapDelta(pointer, thumbProgress, 360) : thumbProgress - pointer, }; } else if (target === "span") { drag = { ...base, mode: "span", lastPointer: pointer, start: current.map((v) => valueToProgress(dial, v)), shift: 0, }; } else { // Elsewhere on the band: jump the nearest thumb there, then hold it. const next = moveThumb( index, progressToValue(dial, pointer), "click", ); drag = { ...base, changed: !sameValues(next, current), mode: "thumb", index, lastPointer: pointer, grabOffset: 0, }; } } dragRef.current = drag; // Synthetic events (tests, automation) carry no live pointer to capture. try { root.setPointerCapture(event.pointerId); } catch {} setPressed(drag.mode === "span" ? "span" : "thumb"); const held = "index" in drag ? drag.index : 0; if ("index" in drag) setActiveIndex(drag.index); // preventDefault stops the compatibility mousedown from moving focus // straight back off the input. event.preventDefault(); focusThumbInput(held); }, [ disabled, size, thickness, inset, variant, dragMode, dial, origin, activeIndex, moveThumb, focusThumbInput, ], ); // Marks what a press under the mouse would hold. const trackHover = React.useCallback( (event: React.PointerEvent) => { if (variant !== "ring" || event.pointerType !== "mouse") return; const g = measurePointer(event, size, thickness, inset); let over: number | "span" | null = null; if (isOnBand(g, dial, size, thickness, inset)) { const current = valuesRef.current; const index = current.length > 1 ? nearestThumb(dial, current, g.angle, activeIndex) : 0; // A vertical drag holds the nearest thumb from anywhere on the band. const target = dragMode === "vertical" ? "thumb" : ringPressTarget(dial, current, g, index, origin); over = target === "span" ? "span" : target === "band" ? null : index; } setHover(over); }, [variant, dragMode, size, thickness, inset, dial, activeIndex, origin], ); const handlePointerMove = React.useCallback( (event: React.PointerEvent) => { const drag = dragRef.current; if (!drag) { trackHover(event); return; } if (drag.pointerId !== event.pointerId) return; if (!drag.moved) { if ( Math.hypot(event.clientX - drag.downX, event.clientY - drag.downY) <= DRAG_THRESHOLD ) { return; } drag.moved = true; } if (!dragging) setDragging(true); const g = measurePointer(event, size, thickness, inset); const period = dial.sweep; // Stored on the current drag, which a pending press replaces. const showDrawn = (next: number[]): void => { const current = dragRef.current; if (!current) return; current.drawn = next; setDrawn(next); }; // Draws a thumb at an unsnapped value, pushing or stopping at the other // as the value does. `before` is the values ahead of this move, since // the move has already pushed the snapped ones. const draw = ( index: number, candidate: number, before: readonly number[], ): void => { if (!smooth) return; showDrawn( placeRangeThumb( dial, dragRef.current?.drawn ?? before, index, dial.wrap ? candidate : clamp(candidate, min, max), thumbGap, thumbCollisionBehavior, { snap: false }, ), ); }; const settle = (progress: number): number => dial.wrap ? mod(progress, period) : clamp(progress, 0, period); const mark = (changed: boolean) => { if (changed) drag.changed = true; }; if (drag.mode === "knob" || drag.mode === "vertical") { if (drag.mode === "knob") { // Near the center a pixel of travel swings the angle wildly, so // ignore it there, without moving the reference angle. const radius = (size / 2) * g.scale; if (g.distance < radius * KNOB_DEAD_ZONE) return; } const delta = drag.mode === "knob" ? wrapDelta(drag.lastAngle, g.angle, 360) * dial.dir : ((drag.lastY - event.clientY) / VERTICAL_DRAG_PX) * period; drag.lastAngle = g.angle; drag.lastY = event.clientY; drag.progress = settle(drag.progress + delta); const before = valuesRef.current; const next = moveThumb( drag.index, progressToValue(dial, drag.progress), "drag", ); mark(!sameValues(next, before)); // Blocked by the other thumb or a gap: restart from where the thumb // actually is, so turning back responds at once. const wanted = snapValue(dial, progressToValue(dial, drag.progress)); if (next[drag.index] !== wanted) { drag.progress = valueToProgress(dial, next[drag.index]); } draw(drag.index, progressToValue(dial, drag.progress), before); return; } if (drag.mode === "span") { const pointer = continueDrag( dial, drag.lastPointer, angleToProgress(dial, g.angle), ); drag.shift += dial.wrap ? wrapDelta(drag.lastPointer, pointer, 360) : pointer - drag.lastPointer; drag.lastPointer = pointer; // Shift both ends by the pointer's total travel since the drag began // (re-snapping per sample would drift), stopping at the dial's ends. if (!dial.wrap) { drag.shift = clamp( drag.shift, -Math.min(...drag.start), period - Math.max(...drag.start), ); } const next = drag.start.map((p) => snapValue(dial, progressToValue(dial, settle(p + drag.shift))), ); mark(commitValues(next, { reason: "drag", activeThumbIndex: -1 })); if (smooth) { showDrawn( drag.start.map((p) => progressToValue(dial, settle(p + drag.shift)), ), ); } return; } // The pointer may run past an end into the gap; add the grab offset // before clamping so a thumb held off-center still reaches min and max. const raw = dial.wrap ? angleToProgress(dial, g.angle) : angleToUnclampedProgress(dial, g.angle); let held: ThumbDrag; if (drag.mode === "pending") { const moved = dial.wrap ? wrapDelta(drag.downPointer, raw, 360) : raw - drag.downPointer; // Wait for a clear direction, measured on screen so finger jitter // does not decide it. if ((Math.abs(moved) * Math.PI * drag.bandRadius) / 180 < PICK_TRAVEL) { return; } const index = pickOverlappedThumb(dial, valuesRef.current, moved > 0); const thumbProgress = valueToProgress(dial, valuesRef.current[index]); held = { ...drag, mode: "thumb", index, lastPointer: drag.downPointer, grabOffset: dial.wrap ? wrapDelta(drag.downPointer, thumbProgress, 360) : thumbProgress - drag.downPointer, }; dragRef.current = held; setActiveIndex(index); focusThumbInput(index); } else if (drag.mode === "thumb") { held = drag; } else { return; } const pointer = continueDrag(dial, held.lastPointer, raw); held.lastPointer = pointer; // Pinned at an end after crossing the seam or the gap's far side: sit // exactly on that end rather than an offset away from it. const target = pointer !== raw ? pointer : settle(pointer + held.grabOffset); const before = valuesRef.current; const next = moveThumb(held.index, progressToValue(dial, target), "drag"); if (!sameValues(next, before)) held.changed = true; draw(held.index, progressToValue(dial, target), before); }, [ dragging, dial, size, thickness, inset, trackHover, smooth, min, max, thumbGap, thumbCollisionBehavior, moveThumb, commitValues, focusThumbInput, ], ); const handlePointerEnd = React.useCallback( (event: React.PointerEvent) => { const drag = dragRef.current; if (!drag || drag.pointerId !== event.pointerId) return; dragRef.current = null; setPressed(false); setDragging(false); if (drag.drawn) { // The arc and thumbs sweep from where they were drawn onto the step. // Across a wrapping dial's seam that sweep would spin the long way // round, so it lands at once instead. const settled = valuesRef.current; if (crossesSeam(dial, drag.drawn, settled)) { setInstantKey(settled.join(",")); } setDrawn(null); } // Guarded: on the cancel and lost-capture paths the capture may already // be gone, and releasing an inactive pointer throws. const root = event.currentTarget; if (root.hasPointerCapture(event.pointerId)) { root.releasePointerCapture(event.pointerId); } if (drag.changed) onValueCommitted?.(emit(valuesRef.current)); // A click may have jumped a thumb under the mouse; mark it now rather // than on the next move. if (event.type === "pointerup") trackHover(event); }, [dial, onValueCommitted, emit, trackHover], ); const handleKeyDown = React.useCallback( (index: number, event: React.KeyboardEvent) => { if (disabled) return; // Keyboard use means keyboard modality, even if focus arrived by pointer. setFocusVisibleIndex(index); const current = valuesRef.current[index]; const big = event.shiftKey ? largeStep : step; let candidate: number | null = null; switch (event.key) { case "ArrowUp": case "ArrowRight": candidate = current + big; break; case "ArrowDown": case "ArrowLeft": candidate = current - big; break; case "PageUp": candidate = current + largeStep; break; case "PageDown": candidate = current - largeStep; break; case "Home": candidate = min; break; case "End": // On a wrapping dial max is min's position, so stop one step short. candidate = dial.wrap ? max - step : max; break; default: return; } event.preventDefault(); const before = valuesRef.current; const next = moveThumb(index, candidate, "keyboard"); setInstantKey(event.key.startsWith("Arrow") ? next.join(",") : null); setActiveIndex(index); if (!sameValues(next, before)) onValueCommitted?.(emit(next)); }, [ disabled, largeStep, step, min, max, dial, moveThumb, onValueCommitted, emit, ], ); // Assistive tech that adjusts the native input directly (VoiceOver swipes) // lands here rather than in keydown. const handleInputChange = React.useCallback( (index: number, event: React.ChangeEvent) => { const before = valuesRef.current; const next = moveThumb(index, Number(event.target.value), "keyboard"); setInstantKey(next.join(",")); if (!sameValues(next, before)) onValueCommitted?.(emit(next)); }, [moveThumb, onValueCommitted, emit], ); const contextValue = React.useMemo( () => ({ dial, values, shown, previousValues: history.previous, origin, size, thickness, inset, thumbShape, variant, pressed: pressed !== false, dragging, activeIndex, heldIndex: pressed === "thumb" ? activeIndex : null, hoverIndex: typeof hover === "number" ? hover : null, focusVisibleIndex, instant, formatValue, }), // `values` is a fresh array for scalar values; key it by content. // eslint-disable-next-line react-hooks/exhaustive-deps [ dial, valuesKey, drawn, history.previous, origin, size, thickness, inset, thumbShape, variant, pressed, dragging, activeIndex, hover, focusVisibleIndex, instant, formatValue, ], ); const vertical = dragMode === "vertical"; const defaultProps = { "data-slot": "circular-slider", "data-variant": variant, "data-color": color, "data-drag-mode": dragMode, "data-pressed": pressed !== false || undefined, "data-dragging": dragging || undefined, "data-instant": instant || undefined, "data-disabled": disabled || undefined, "data-range": isRange || undefined, "data-grab-hover": hover !== null || undefined, // Base UI drawers and toasts don't swipe from a drag on the dial. A knob // owns its whole face; a ring only its band (marked below). "data-base-ui-swipe-ignore": variant === "knob" ? "" : undefined, // A range is two sliders; the group carries the shared name and each // thumb its own ("Start", "End"). ...(isRange && { role: "group", "aria-label": ariaLabel, "aria-labelledby": ariaLabelledby, }), className: cn( // A knob is all face, so it owns every touch on it. A ring only owns // touches on its band (the band layer below); swipes that start in the // middle still scroll the page. "group/circular-slider relative shrink-0 select-none", color === "primary" ? "[--circular-slider-fill:var(--primary)] [--circular-slider-fill-foreground:var(--primary-foreground)]" : "[--circular-slider-fill:var(--emphasis)] [--circular-slider-fill-foreground:var(--emphasis-foreground)]", variant === "knob" && "touch-none", "data-disabled:pointer-events-none data-disabled:opacity-60", // A partial ring is shorter than its square. Clip just below the bottom // so the empty rest never catches clicks (clip-path clips hit-testing // too); other sides keep room for focus rings and the pill. height < size && "[clip-path:inset(-24px_-24px_-8px_-24px)]", variant === "knob" && !disabled && (vertical ? "cursor-ns-resize" : "cursor-grab data-pressed:cursor-grabbing"), className, ), style: { width: size, aspectRatio: `${size} / ${height}`, "--circular-slider-size": `${size}px`, // The open middle of the dial, for content centered in it. "--circular-slider-hole": `${Math.max(0, size - 2 * (variant === "knob" ? thickness + KNOB_GAP : inset + thickness))}px`, ...style, } as React.CSSProperties, onPointerDown: handlePointerDown, onPointerMove: handlePointerMove, onPointerUp: handlePointerEnd, // An OS-cancelled gesture (touch interruption, context menu) never sends // pointerup; these still end the drag and commit. onPointerCancel: handlePointerEnd, onLostPointerCapture: handlePointerEnd, onPointerLeave: () => setHover(null), children: ( // The dial's square, anchored to the top so a half dial can be shorter.

{variant === "ring" && (

)} {values.map((thumbValue, index) => ( { inputRefs.current[index] = node; }} type="range" min={min} max={max} step={step} value={thumbValue} disabled={disabled} name={name} form={form} id={index === 0 ? id : undefined} aria-label={ getAriaLabel?.(index) ?? (isRange ? (index === 0 ? "Start" : "End") : ariaLabel) } aria-labelledby={isRange ? undefined : ariaLabelledby} aria-describedby={ariaDescribedby} aria-valuetext={spokenValue?.(thumbValue, index)} className="sr-only" onChange={(event) => handleInputChange(index, event)} onKeyDown={(event) => handleKeyDown(index, event)} onFocus={() => { setActiveIndex(index); setFocusVisibleIndex(focusFromPointer.current ? null : index); focusFromPointer.current = false; }} onBlur={() => setFocusVisibleIndex(null)} /> ))} {children}

), }; const element = useRender({ defaultTagName: "div", render, props: mergeProps<"div">(defaultProps, props), }); return ( {element} ); } /** * Clip for the band's hit layer: the swept arc plus slop. clip-path also * clips hit-testing, so the middle and a partial sweep's gap stay free. */ function bandClipPath( dial: Dial, size: number, thickness: number, inset: number, ): string { const c = size / 2; const outer = c + BAND_SLOP; const inner = Math.max(0, c - inset - thickness - BAND_SLOP); const circle = (r: number): string => `M ${c - r} ${c} a ${r} ${r} 0 1 0 ${2 * r} 0 a ${r} ${r} 0 1 0 ${-2 * r} 0 Z`; if (dial.sweep >= 360) { return `path(evenodd, "${circle(outer)} ${circle(inner)}")`; } const radius = bandRadius(size, thickness, inset); const edge = slopDegrees(thickness / 2 + BAND_SLOP, radius); const first = (dial.dir === 1 ? dial.start : dial.start - dial.sweep) - edge; const span = Math.min(359.9, dial.sweep + edge * 2); const last = first + span; const at = (r: number, angle: number): string => { const rad = (angle * Math.PI) / 180; return `${round(c + r * Math.sin(rad))} ${round(c - r * Math.cos(rad))}`; }; const large = span > 180 ? 1 : 0; return `path("M ${at(outer, first)} A ${outer} ${outer} 0 ${large} 1 ${at(outer, last)} L ${at(inner, last)} A ${inner} ${inner} 0 ${large} 0 ${at(inner, first)} Z")`; } /** Classes that animate a value change and stand still while dragging. */ const SETTLE_TRANSITION = "duration-350 ease-(--ease-out-expo) group-data-dragging/circular-slider:transition-none group-data-instant/circular-slider:transition-none motion-reduce:transition-none"; function overlayProps(slot: string, size: number, className?: string) { return { "data-slot": slot, "aria-hidden": true, viewBox: `0 0 ${size} ${size}`, className: cn( "pointer-events-none absolute inset-0 size-full overflow-visible", className, ), }; } function bandRadius(size: number, thickness: number, inset = 0): number { return size / 2 - inset - thickness / 2; } /** * How far a pill thumb reaches past each side of the band. The band moves in * by the same amount so the pill stays inside the dial's box. */ function pillOverhang(thickness: number): number { // At least long enough (12px) to see and aim at, however thin the band. return Math.max( 3, Math.round(thickness * 0.3), Math.ceil((12 - thickness) / 2), ); } function pillWidth(thickness: number): number { return clamp(Math.round(thickness / 3), 4, 6); } /** * Progress the track is drawn over. With a pill, the ends pull in so the * round cap ends flush with the pill instead of a sliver showing past it, * like Base UI's `thumbAlignment="edge"`. */ function trackSpan( dial: Dial, radius: number, thickness: number, thumbShape: "bead" | "pill", ): Span { if (thumbShape !== "pill" || dial.sweep >= 360) { return { from: 0, length: dial.sweep }; } const px = thickness / 2 - pillWidth(thickness) / 2; const degrees = ((px / radius) * 180) / Math.PI; return { from: degrees, length: Math.max(0, dial.sweep - degrees * 2) }; } const svgRotateStyle = { transformBox: "view-box", transformOrigin: "50% 50%", } as const satisfies React.CSSProperties; export type CircularSliderTrackProps = useRender.ComponentProps<"svg">; /** The full sweep of the band, drawn behind the indicator. */ function CircularSliderTrack({ className, render, ...props }: CircularSliderTrackProps) { const { dial, size, thickness, inset, thumbShape } = useCircularSliderContext(); const radius = bandRadius(size, thickness, inset); const stroke = arcStroke( dial, radius, trackSpan(dial, radius, thickness, thumbShape), ); return useRender({ defaultTagName: "svg", render, props: mergeProps<"svg">( overlayProps("circular-slider-track", size, className), props, { children: ( ), }, ), }); } export type CircularSliderIndicatorProps = useRender.ComponentProps<"svg">; /** * The filled arc: from `origin` to the value, or between a range's thumbs. * Sweeps on click, Home/End/Page and outside changes; arrow steps and drags * land at once. */ function CircularSliderIndicator({ className, render, ...props }: CircularSliderIndicatorProps) { const { dial, shown: values, origin, size, thickness, inset, thumbShape, } = useCircularSliderContext(); const radius = bandRadius(size, thickness, inset); const capDegrees = ((thickness / 2 / radius) * 180) / Math.PI; const span = getActiveSpan(dial, values, origin); // From a reference reading (not min), start the arc at the reading itself. const fromReference = values.length === 1 && origin !== dial.min; const drawn = fromReference ? trimOriginCap( span, valueToProgress(dial, values[0]), valueToProgress(dial, origin), capDegrees, ) : span; const hidden = fromReference && drawn.length === 0; // useId output can hold characters that break a url(#...) reference. const maskId = `circular-slider-mask-${React.useId().replace(/[^\w-]/g, "")}`; const isPill = thumbShape === "pill"; // A round end would bulge past a slim pill, so with a pill the ends are cut // flat and the arc is masked to the track, letting the free end fill the // track's rounded tip without poking outside it. let pillSpan: Span | null = null; if (isPill) { const startsAtMin = values.length === 1 && origin === dial.min; const reach = dial.sweep < 360 && startsAtMin ? capDegrees : 0; pillSpan = { from: span.from - reach, length: span.length + reach }; } const track = trackSpan(dial, radius, thickness, thumbShape); const indicatorArc = (piece: Span, cap: "round" | "butt") => { const stroke = arcStroke(dial, radius, piece); return ( ); }; const trackStroke = arcStroke(dial, radius, track); const c = size / 2; return useRender({ defaultTagName: "svg", render, props: mergeProps<"svg">( overlayProps("circular-slider-indicator", size, className), props, { children: isPill ? ( <> {indicatorArc(pillSpan as Span, "butt")} ) : ( indicatorArc(drawn, "round") ), }, ), }); } export interface CircularSliderThumbProps extends useRender.ComponentProps<"svg"> { /** * Bead diameter in px. Defaults to the band's thickness less 4px. Applies * to `thumbShape="bead"` only; a pill's shape follows the band. */ beadSize?: number; } /** * One thumb per value, set into the end of the indicator. * * Drawn in SVG in the indicator's rotated space so both share a rasterizer: * an HTML bead over an SVG arc reads as off-center at fractional scales. * Rotating about the center makes value changes travel along the arc. */ function CircularSliderThumb({ className, render, beadSize, ...props }: CircularSliderThumbProps) { const { dial, shown: values, size, thickness, inset, thumbShape, pressed, activeIndex, heldIndex, hoverIndex, focusVisibleIndex, } = useCircularSliderContext(); const isPill = thumbShape === "pill"; const bead = beadSize ?? Math.max(4, thickness - 4); const radius = bandRadius(size, thickness, inset); const c = size / 2; // Center of the band at 12 o'clock, before each thumb is rotated into place. const cy = inset + thickness / 2; const pillW = pillWidth(thickness); const pillH = thickness + inset * 2; const progresses = values.map((v) => valueToProgress(dial, v)); // When a range's beads would touch, a bridge fills the short way between // them so they read as one pill. Always mounted so it sweeps with them. let bridge: Span | null = null; let merged = false; if (!isPill && progresses.length === 2) { const [p0, p1] = progresses; let from = Math.min(p0, p1); let length = Math.abs(p1 - p0); if (dial.wrap) { const forward = mod(p1 - p0, 360); from = forward <= 180 ? p0 : p1; length = Math.min(forward, 360 - forward); } bridge = { from, length }; merged = (length * Math.PI * radius) / 180 < bead + 2; } // The thumb in front is the one last moved. const order = values .map((_, index) => index) .sort((a, b) => Number(a === activeIndex) - Number(b === activeIndex)); const rotated = (angle: number): React.CSSProperties => ({ ...svgRotateStyle, rotate: `${round(angle)}deg`, }); const capsule = ( w: number, h: number, extra: React.SVGProps, ) => ( ); const thumbState = (index: number) => ({ "data-slot": "circular-slider-thumb", "data-index": index, "data-shape": thumbShape, "data-active": index === activeIndex || undefined, "data-pressed": index === heldIndex || undefined, "data-hovered": (!pressed && index === hoverIndex) || undefined, }); // Grows under the mouse and more on grab; a bead stays inside the band. const growClasses = cn( "[transform-origin:center] [transform-box:fill-box]", "transition-[scale] duration-150 ease-out motion-reduce:transition-none", isPill ? "data-hovered:scale-108 data-pressed:scale-112" : "data-hovered:scale-110 data-pressed:scale-115", ); const focusIndex = focusVisibleIndex !== null && progresses[focusVisibleIndex] !== undefined ? focusVisibleIndex : null; const ring = isPill ? { w: pillW + 7, h: pillH + 7 } : null; const children = ( <> {bridge && ( )} {order.map((index) => ( {isPill ? ( // The pill crosses both the track and the filled arc, so a // hairline and a soft shadow keep it distinct on both, the light // track included. The shadow is centered: an offset would turn // with the thumb. {capsule(pillW + 1, pillH + 1, { className: "fill-black/14" })} {capsule(pillW, pillH, { className: "fill-(--circular-slider-fill-foreground)", })} ) : ( )} ))} {/* Focus: a full-strength ring, edged with the page color on both sides so it stays distinct where it crosses the filled arc. */} {focusIndex !== null && ( {ring ? ( <> {capsule(ring.w, ring.h, { fill: "none", strokeWidth: 5, className: "stroke-background", })} {capsule(ring.w, ring.h, { fill: "none", strokeWidth: 2, className: "stroke-ring", })} ) : ( <> )} )} ); return useRender({ defaultTagName: "svg", render, props: mergeProps<"svg">( overlayProps("circular-slider-thumbs", size, className), props, { children }, ), }); } export interface CircularSliderTicksProps extends useRender.ComponentProps<"svg"> { /** Number of intervals across the sweep. */ count?: number; /** Tick length in px. */ length?: number; } /** * A scale of ticks: inside a ring's band, or as a knob's band. Ticks up to * the value light, in step with the indicator's sweep. */ function CircularSliderTicks({ className, render, count, length, ...props }: CircularSliderTicksProps) { const { dial, values, shown, previousValues, origin, size, thickness, inset, variant, dragging, instant, } = useCircularSliderContext(); const isKnob = variant === "knob"; const tickCount = count ?? (isKnob ? 30 : 20); const tickLength = length ?? (isKnob ? thickness : 4); const outerY = isKnob ? 1 : inset + thickness + 4; const tickWidth = isKnob ? 2 : 1.5; // Also light the nearest tick, so a value just short of a tick still lights // it. Just under half an interval, so a midpoint never lights both. const halfInterval = (dial.sweep / Math.max(1, Math.round(tickCount)) / 2) * 0.999; const span = widenSpan(getActiveSpan(dial, shown, origin), halfInterval); const previousSpan = widenSpan( getActiveSpan(dial, previousValues, origin), halfInterval, ); // The tick sweep follows the one thumb that moved. A range shifted as a // whole, or several thumbs at once, changes its ticks together. const movedIndex = previousValues.length === values.length ? values.findIndex((v, i) => v !== previousValues[i]) : -1; const movedCount = values.filter((v, i) => v !== previousValues[i]).length; const headFrom = movedIndex >= 0 ? valueToProgress(dial, previousValues[movedIndex]) : 0; const headTo = movedIndex >= 0 ? valueToProgress(dial, values[movedIndex]) : 0; const travel = Math.abs(headTo - headFrom); const ticks = tickProgresses(dial, tickCount).map((progress) => { const lit = isInSpan(dial, progress, span); const wasLit = isInSpan(dial, progress, previousSpan); let delay = 0; if ( !dragging && !instant && lit !== wasLit && movedCount === 1 && travel > 0 ) { const share = clamp(Math.abs(progress - headFrom) / travel, 0, 1); delay = Math.round(easeOutExpoTimeAt(share) * SETTLE_MS); } return { progress, lit, delay }; }); return useRender({ defaultTagName: "svg", render, props: mergeProps<"svg">( overlayProps("circular-slider-ticks", size, className), props, { children: ticks.map((tick) => ( )), }, ), }); } export interface CircularSliderMarkProps extends useRender.ComponentProps<"svg"> { /** The reading to mark, e.g. the current temperature. */ value: number; } /** A read-only mark across the band for a second value, such as a current reading. */ function CircularSliderMark({ className, render, value, ...props }: CircularSliderMarkProps) { const { dial, size, thickness, inset, thumbShape, variant } = useCircularSliderContext(); const angle = progressToAngle( dial, valueToProgress(dial, clamp(value, dial.min, dial.max)), ); // Rendered rotation, kept unwrapped so crossing a wrapping dial's seam // (355 to 5) turns the short way. Updated during render ("previous props"). const [shown, setShown] = React.useState(angle); let rotation = shown; if (round(mod(shown, 360)) !== round(mod(angle, 360))) { rotation = dial.wrap ? shown + wrapDelta(mod(shown, 360), mod(angle, 360), 360) : angle; setShown(rotation); } const isKnob = variant === "knob"; // Beside a pill thumb the mark spans the same length, so the reading and // the target read as a matching pair of lines bracketing the span. const matchPill = !isKnob && thumbShape === "pill"; const y1 = isKnob ? -2 : matchPill ? 0 : inset + 1; const y2 = isKnob ? thickness + 2 : matchPill ? inset * 2 + thickness : inset + thickness + 4; return useRender({ defaultTagName: "svg", render, props: mergeProps<"svg">( overlayProps("circular-slider-mark", size, className), props, { children: ( // Rotated as one group so the edge and the line never drift apart. {/* A page-colored edge keeps the mark legible on the filled arc. */} ), }, ), }); } export type CircularSliderKnobProps = useRender.ComponentProps<"div">; /** * The raised face of a `knob` dial. It turns with the value, carrying a * notch, and presses in slightly while held. */ function CircularSliderKnob({ className, render, children, ...props }: CircularSliderKnobProps) { const { dial, values, shown, previousValues, size, thickness, thumbShape, dragging, heldIndex, focusVisibleIndex, } = useCircularSliderContext(); // The face follows the thumb being dragged, else the one whose value last // changed, not the focused one, so moving focus between a range's thumbs // never turns it. const [faceIndex, setFaceIndex] = React.useState(0); const moved = dragging && heldIndex !== null ? heldIndex : values.findIndex((v, i) => v !== previousValues[i]); if (moved >= 0 && moved !== faceIndex) setFaceIndex(moved); const value = shown[Math.min(moved >= 0 ? moved : faceIndex, shown.length - 1)]; const angle = progressToAngle(dial, valueToProgress(dial, value)); const insetPercent = ((thickness + KNOB_GAP) / size) * 100; const element = useRender({ defaultTagName: "div", render, props: mergeProps<"div">( { "aria-hidden": true, "data-slot": "circular-slider-knob", "data-focus-visible": focusVisibleIndex !== null || undefined, className: cn( "absolute overflow-hidden rounded-full bg-surface-4 shadow-(--surface-shadow-combined-4) group-hover/circular-slider:shadow-(--surface-shadow-combined-5) group-data-disabled/circular-slider:shadow-(--surface-shadow-combined-4)", "transition-[scale,box-shadow,outline-color] duration-150 ease-out", "group-data-pressed/circular-slider:scale-[0.98] motion-reduce:group-data-pressed/circular-slider:scale-100", "outline-2 -outline-offset-1 outline-transparent data-focus-visible:outline-ring", className, ), style: { inset: `${insetPercent}%` }, children: ( {children ?? ( )} ), } as React.ComponentProps<"div">, props, ), }); return element; } export interface CircularSliderValueProps extends Omit< useRender.ComponentProps<"div">, "children" > { /** * Formats each value. Defaults to the root's `formatValue`, which screen * readers also speak; set it on the root to keep the two in step. */ formatValue?: (value: number, index: number) => string; /** Joins the two ends of a range. */ separator?: string; } /** The current value as text, centered in the dial. */ function CircularSliderValue({ className, render, formatValue, separator = " – ", ...props }: CircularSliderValueProps) { const { values, formatValue: rootFormat } = useCircularSliderContext(); const format = formatValue ?? rootFormat; const text = values .map((value, index) => (format ? format(value, index) : String(value))) .join(separator); return useRender({ defaultTagName: "div", render, props: mergeProps<"div">( { "data-slot": "circular-slider-value", "aria-hidden": true, className: cn( // Truncates inside the open middle rather than running over the // arc (screen readers read the hidden input). leading-tight keeps // the truncation clip off descenders and tall accents. "pointer-events-none relative max-w-[calc(var(--circular-slider-hole)-0.5rem)] truncate text-[length:max(0.6875rem,calc(var(--circular-slider-size)*0.17))] leading-tight font-semibold tabular-nums", className, ), children: text, } as React.ComponentProps<"div">, props, ), }); } export interface CircularSliderProps< Value extends SliderValue = number, > extends Omit, "variant" | "formatValue"> { /** * Formats the centered value, and what screen readers speak unless * `getAriaValueText` says otherwise. Pass `null` to hide the value. */ formatValue?: ((value: number, index: number) => string) | null; } /** * The ready-made ring: the band with its indicator, a thumb per value and * the value in the middle. Compose the parts with `CircularSliderRoot` for * anything else (a knob, ticks, a reference mark, custom center content). */ function CircularSlider({ formatValue, children, ...props }: CircularSliderProps) { return ( {formatValue !== null && } {children} ); } export type { CircularSliderDirection, ThumbCollision }; export { CircularSlider, CircularSliderRoot, CircularSliderTrack, CircularSliderIndicator, CircularSliderThumb, CircularSliderTicks, CircularSliderMark, CircularSliderKnob, CircularSliderValue, };