# Click Wheel
> An unstyled rotary input for React with pointer, scroll and keyboard controls, haptics and optional inertia.
## Install
```bash
pnpm add click-wheel
```
Requires React 19.2 or newer. Import `{ ClickWheel }` from `"click-wheel"`.
## Optional themes
Add a theme to a project configured for shadcn. Each theme depends on the npm package.
- `pnpm dlx shadcn@latest add https://click-wheel.jackymo.me/r/click-wheel-shadcn.json`
- `pnpm dlx shadcn@latest add https://click-wheel.jackymo.me/r/click-wheel-ipod.json`
- `pnpm dlx shadcn@latest add https://click-wheel.jackymo.me/r/click-wheel-retro.json`
- `pnpm dlx shadcn@latest add https://click-wheel.jackymo.me/r/click-wheel-galley.json`
## Docs
- [All docs as one Markdown file](https://click-wheel.jackymo.me/docs.md)
- [Getting Started](https://click-wheel.jackymo.me/docs): An unstyled rotary input for React.
- [Styling](https://click-wheel.jackymo.me/docs/styling): Style the parts with data attributes, CSS variables or functions of state..
- [API Reference](https://click-wheel.jackymo.me/docs/api)
- [Default](https://click-wheel.jackymo.me/examples/default): Examples of styling, gearing, detents, inertia and controlled state..
- [Themes](https://click-wheel.jackymo.me/examples/themes)
- [Everything in one file](https://click-wheel.jackymo.me/llms-full.txt): the docs plus the full component source
- [Registry index](https://click-wheel.jackymo.me/r/registry.json)
## Quick reference
```tsx
import { ClickWheel } from "click-wheel";
```
- Parts have no default visual styles. State: `data-dragging` (a pointer holds the ring), `data-coasting` (coasting after release), `data-disabled`, `--click-wheel-fraction` (0–1), `--click-wheel-turns` (laps from min), `--click-wheel-rotation` (deg). `className` and `style` may be functions of `{ value, dragging, coasting, disabled }`. Every part takes a `render` prop.
- Gearing: `unitsPerTurn` sets how far one revolution moves the value. `detent` sets the units between haptic ticks. `inertia` (off by default) keeps the wheel spinning after a flick; `decelerationRate` (0.998) is the velocity kept per millisecond.
- Callbacks: `onValueChange` on every change, `onValueCommitted` once per completed interaction, `onInteractionChange` across pointer, scroll, keyboard and coasting (including cancellation), `onDraggingChange` when a pointer starts or stops dragging, `onTick` per detent.
- Haptics: Vibration API on Android; the switch trick on iOS 17.4–26.4; on iOS 26.5+ only real taps vibrate, so put `` inside the center button.
---
# Click Wheel docs
> Documentation for https://click-wheel.jackymo.me/docs. Component source: https://click-wheel.jackymo.me/llms-full.txt
## Getting Started
An unstyled rotary input for React. Supports dragging, scrolling, keyboard input, haptics and optional inertia.
Page: https://click-wheel.jackymo.me/docs
### Installation
```bash
pnpm add click-wheel
```
### Create a click wheel
**player.tsx**
```tsx
import { ClickWheel } from "click-wheel";
```
`Root` manages the value and interactions. `Ring` handles pointer, scroll and keyboard input. `Rotor` rotates with the gesture. `Center` is a button that does not start a drag. Use `value` for controlled state or `defaultValue` for uncontrolled state.
### Style it
Add styles with `className` or `style`. This example uses Tailwind classes.
**examples/basic.tsx**
```tsx
"use client";
import * as React from "react";
import { ClickWheel } from "click-wheel";
const DURATION = 227;
function fmt(s: number) {
return `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, "0")}`;
}
export function Basic() {
const [seconds, setSeconds] = React.useState(72);
return (
);
}
```
## Styling
Style the parts with data attributes, CSS variables or functions of state.
Page: https://click-wheel.jackymo.me/docs/styling
### Data attributes
Every part exposes `data-dragging`, `data-coasting` and `data-disabled`. Use them with Tailwind variants or CSS attribute selectors.
**Tailwind**
```tsx
```
### CSS variables
`Root` sets three variables. `--click-wheel-fraction` is the value as a number from 0 to 1. `--click-wheel-turns` is the value's distance from `min` in revolutions, so 1.5 means one and a half revolutions. `--click-wheel-rotation` is the cumulative angle of the rotor in degrees. During a gesture they update directly from the continuous position. When it ends, progress reconciles to the accepted value, including any step rounding. Changes to bounds and gearing also update progress.
**wheel.css**
```css
.arc {
background: conic-gradient(
var(--primary) calc(var(--click-wheel-fraction) * 360deg),
transparent 0
);
}
.groove-3 {
background: conic-gradient(
var(--primary) calc(clamp(0, calc(var(--click-wheel-turns) - 2), 1) * 360deg),
transparent 0
);
}
.needle {
rotate: var(--click-wheel-rotation, 0deg);
}
```
`Rotor` sets `will-change: transform` to reduce repainting during rotation. Avoid CSS transitions on `rotate`; restarting a transition on each pointer update can cause stuttering.
### Functions of state
`className` and `style` accept a function of the part's state. The state is `{ value, dragging, coasting, disabled }`.
**className as a function**
```tsx
(state.dragging ? "ring ring-held" : "ring")}
style={(state) => ({ opacity: state.disabled ? 0.5 : 1 })}
/>
```
### The render prop
Replace a part's element or compose it with your own component. Handlers chain, class names join, other props override. Refs are composed, including callback cleanup functions. Custom components must forward the received props and ref.
**render**
```tsx
} />
} />
```
## API Reference
Page: https://click-wheel.jackymo.me/docs/api
### Anatomy
**anatomy**
```tsx
import { ClickWheel } from "click-wheel";
```
### Root
Renders a `div`. Holds the value, the gestures, and the CSS variables.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | number | — | Controlled value. The accepted prop determines the value and settled progress. |
| defaultValue | number | min | Starting value when uncontrolled. |
| min | number | 0 | Lower bound. |
| max | number | 100 | Upper bound. |
| step | number | 1 | Granularity of emitted values. Also the arrow-key step. Both bounds remain reachable even when off the step grid. |
| unitsPerTurn | number | 100 | The gearing: how far one full revolution moves the value. |
| detent | number | 0 | Units between detents. onTick fires for every crossing, including multiple crossings in one update. 0 disables detents. |
| haptics | boolean | true | Pulse the motor when detents are crossed, where supported. Multiple crossings in one update share a pulse. |
| inertia | boolean | false | Continue spinning after release. Touch resumes dragging; scroll and keyboard input stop coasting. |
| decelerationRate | number | 0.998 | Velocity retained per millisecond while coasting. Lower values stop sooner. |
| disabled | boolean | false | Inert. Cancels an active interaction without committing, sets data-disabled on every part, and omits the hidden input from form submission. |
| name | string | — | Renders a hidden input with this name, for forms. |
| onValueChange | (value: number, details: ChangeDetails) => void | — | Fires on every change while dragging, coasting, scrolling or keying. |
| onValueCommitted | (value: number, details: ChangeDetails) => void | — | Fires once when an interaction completes, even if the value did not change. With inertia, waits until the wheel settles. Cancelled interactions do not commit. |
| onInteractionChange | (active: boolean, details: InteractionDetails) => void | — | Brackets pointer, scroll and keyboard interactions, including coasting. Always ends, including cancellation and unmount. |
| onDraggingChange | (dragging: boolean) => void | — | Reports only when a pointer takes or releases the ring. Use onInteractionChange to track the full interaction, including coasting, scroll and keyboard input. |
| onTick | (direction: 1 \| -1) => void | — | Fires per detent crossing, with the direction of travel. |
### Interaction lifecycle
`ClickWheel.ChangeDetails` contains `source`: `pointer`, `wheel`, or `keyboard`. `ClickWheel.InteractionDetails` also contains `cancelled`. An interaction starts with `onInteractionChange(true)`, emits value changes, commits once, then ends with `onInteractionChange(false)`. A pointer interaction includes its coast; grabbing that coast continues the same interaction. Scroll events are grouped until 150 ms of inactivity; each keyboard action commits immediately.
Disabling, pointer cancellation, losing capture, window blur during a drag, or unmounting ends the interaction with `cancelled: true` and no commit. Already accepted values remain. Use `onInteractionChange` to suspend and resume playback-driven updates, and `onValueCommitted` to seek. `onDraggingChange` only reports whether a pointer holds the ring.
### Ring
Renders a `div` with `role="slider"`. Pointer, scroll and keyboard input live here.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| aria-label | string | — | The accessible name. The ring is the slider. |
| getAriaValueText | (value: number) => string | — | Formats the value for screen readers, e.g. seconds to “1 min 20 sec”. |
### Rotor
Renders an `aria-hidden` `div` with `rotate: var(--click-wheel-rotation)`. Rotates with pointer movement. Has no additional props.
### Center
Renders a `button` with `type=button`, including when composed with `render`. An explicit `type=submit` is respected. Pass `onClick` and an `aria-label`, or render a `div` for a plain hub. A disabled Root prevents Center activation even when a custom element overrides its disabled prop.
### Common props
Every part accepts these, plus the props of the element it renders.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| className | string \| (state) => string | — | A class string, or a function of the part's state. |
| style | CSSProperties \| (state) => CSSProperties | — | A style object, or a function of the part's state. |
| render | ReactElement \| (props, state) => ReactElement | — | Replace the default element or compose with your own component. Props merge: handlers chain, classes join. |
### State
The object passed to `className`, `style` and `render` functions, exported as `ClickWheel.State`.
| Field | Type | Description |
| --- | --- | --- |
| value | number | The current value. |
| dragging | boolean | A pointer is holding the ring. |
| coasting | boolean | The ring is coasting after release. |
| disabled | boolean | The wheel is disabled. |
### Helpers
| Export | Type | Description |
| --- | --- | --- |
| haptic(ms?) | (durationMs?: number) => void | One pulse. The duration applies to the Vibration API, default 4. |
| hapticsSupported() | () => boolean | Whether the browser supports a haptics method used by the component. |
| | input props | An invisible switch that covers its parent so a real tap ticks on iOS. The click still bubbles. |
### Keyboard
| Key | Action |
| --- | --- |
| Arrow Up / Arrow Right | + step |
| Arrow Down / Arrow Left | − step |
| Page Up / Page Down | ± one sixth of a turn |
| Home / End | min / max |
The ring announces itself as a slider with `aria-valuenow`, `aria-valuemin` and `aria-valuemax`. Use `getAriaValueText` for a spoken format.
## Default
Examples of styling, gearing, detents, inertia and controlled state.
Page: https://click-wheel.jackymo.me/examples/default
### Basic
The four parts with Tailwind classes. One lap is one minute; a detent every five seconds.
**examples/basic.tsx**
```tsx
"use client";
import * as React from "react";
import { ClickWheel } from "click-wheel";
const DURATION = 227;
function fmt(s: number) {
return `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, "0")}`;
}
export function Basic() {
const [seconds, setSeconds] = React.useState(72);
return (
);
}
```
### Theme installation
The following examples use the shadcn theme. Add it to a project configured for shadcn before copying the examples.
```bash
pnpm dlx shadcn@latest add https://click-wheel.jackymo.me/r/click-wheel-shadcn.json
```
### Gearing
`unitsPerTurn` sets the value change per revolution. A smaller value gives finer control without changing `min` or `max`.
**examples/gearing.tsx**
```tsx
"use client";
import * as React from "react";
import { Wheel } from "@/components/click-wheel-shadcn/wheel";
const DURATION = 227;
const GEARINGS = [30, 60, 300];
function fmt(s: number) {
return `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, "0")}`;
}
export function Gearing() {
const [seconds, setSeconds] = React.useState(72);
const [unitsPerTurn, setUnitsPerTurn] = React.useState(60);
return (
{GEARINGS.map((units) => (
))}
{fmt(seconds)}
);
}
```
### Detents
`detent` sets the units between clicks. Each crossing fires `onTick`, which here plays a short blip. Haptics pulse once per update that crosses a detent.
**examples/detents.tsx**
```tsx
"use client";
import * as React from "react";
import { Wheel } from "@/components/click-wheel-shadcn/wheel";
let ctx: AudioContext | null = null;
function click() {
ctx ??= new AudioContext();
if (ctx.state === "suspended") void ctx.resume();
const osc = ctx.createOscillator();
const gain = ctx.createGain();
osc.type = "square";
osc.frequency.value = 1800;
gain.gain.setValueAtTime(0.03, ctx.currentTime);
gain.gain.exponentialRampToValueAtTime(0.0001, ctx.currentTime + 0.012);
osc.connect(gain).connect(ctx.destination);
osc.start();
osc.stop(ctx.currentTime + 0.014);
}
export function Detents() {
const [value, setValue] = React.useState(40);
const [ticks, setTicks] = React.useState(0);
const [sound, setSound] = React.useState(true);
return (
{
setTicks((n) => n + 1);
if (sound) click();
}}
label="Volume"
className="w-48"
/>
{value} · {ticks} ticks
);
}
```
### Inertia
Enable `inertia` to keep the wheel spinning after release. Touching the ring resumes dragging; scroll and keyboard input stop coasting. `data-coasting` marks this state, and `onValueCommitted` fires when it settles. `decelerationRate` controls the slowdown: lower values stop sooner.
**examples/inertia.tsx**
```tsx
"use client";
import * as React from "react";
import { Wheel } from "@/components/click-wheel-shadcn/wheel";
const RATES = [
{ label: "normal", rate: 0.998 },
{ label: "fast stop", rate: 0.99 },
];
export function Inertia() {
const [value, setValue] = React.useState(40);
const [inertia, setInertia] = React.useState(true);
const [rate, setRate] = React.useState(0.998);
return (
{RATES.map((r) => (
))}
);
}
```
### Controlled
Own the value with `value` and `onValueChange`. `onInteractionChange` tells you when the wheel owns the position, including scroll, keyboard and coasting. Freeze playback-driven readout updates while active, then seek the audio in `onValueCommitted`. Audio can keep playing throughout.
**examples/controlled.tsx**
```tsx
"use client";
import * as React from "react";
import { Wheel } from "@/components/click-wheel-shadcn/wheel";
const DURATION = 227;
function fmt(s: number) {
return `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, "0")}`;
}
export function Controlled() {
const [seconds, setSeconds] = React.useState(72);
const [playing, setPlaying] = React.useState(false);
const [held, setHeld] = React.useState(false);
const [log, setLog] = React.useState([]);
React.useEffect(() => {
if (!playing || held) return;
const id = setInterval(() => setSeconds((s) => (s + 1) % DURATION), 1000);
return () => clearInterval(id);
}, [playing, held]);
return (