Wheel Picker
iOS-style 3D drum picker with flick momentum, built with React and Motion.
Source: https://kokonutui.com/docs/inputs/wheel-picker
Installation
npx shadcn@latest add @kokonutui/wheel-picker
Props
| Prop |
Type |
Default |
Description |
columns? |
WheelColumn[] |
built-in |
|
value? |
Record<string, string> |
|
Controlled selection, keyed by column id. |
defaultValue? |
Record<string, string> |
built-in |
Initial selection when uncontrolled. |
onValueChange? |
(value: Record<string, string>) => void |
|
Called once a wheel comes to rest on a new option. |
label? |
string |
"Time" |
Accessible name for the whole picker. |
className? |
string |
|
Extra classes for the root element. |
WheelColumn
| Field |
Type |
Description |
id |
string |
|
label |
string |
Accessible name of the column, e.g. "Hours". |
options |
WheelOption[] |
|
loop? |
boolean |
Wrap around from the last option to the first. |
className? |
string |
Tailwind width class for the column. |
WheelOption
| Field |
Type |
Description |
value |
string |
|
label |
string |
|
Source
"use client";
/**
* @author: @dorianbaffier
* @description: Wheel Picker
* @version: 1.0.0
* @date: 2026-10-13
* @license: MIT
* @website: https://kokonutui.com
* @github: https://github.com/kokonut-labs/kokonutui
*/
import {
type AnimationPlaybackControls,
animate,
type MotionValue,
motion,
useMotionValue,
useMotionValueEvent,
useReducedMotion,
useTransform,
} from "motion/react";
import {
type KeyboardEvent,
type PointerEvent,
useEffect,
useRef,
useState,
} from "react";
import { cn } from "@/lib/utils";
export interface WheelOption {
value: string;
label: string;
}
export interface WheelColumn {
id: string;
/** Accessible name of the column, e.g. "Hours". */
label: string;
options: WheelOption[];
/** Wrap around from the last option to the first. */
loop?: boolean;
/** Tailwind width class for the column. */
className?: string;
}
const range = (count: number, format: (i: number) => string) =>
Array.from({ length: count }, (_, i) => ({
value: String(i),
label: format(i),
}));
const DEFAULT_COLUMNS: WheelColumn[] = [
{
id: "hour",
label: "Hours",
loop: true,
className: "w-16",
options: range(12, (i) => String(i + 1)),
},
{
id: "minute",
label: "Minutes",
loop: true,
className: "w-16",
options: range(60, (i) => String(i).padStart(2, "0")),
},
{
id: "period",
label: "AM or PM",
className: "w-16",
options: [
{ value: "am", label: "AM" },
{ value: "pm", label: "PM" },
],
},
];
const DEFAULT_VALUE: Record<string, string> = {
hour: "8",
minute: "41",
period: "am",
};
const ITEM_HEIGHT = 36;
// Each row sits this many degrees further round the drum.
const ITEM_ANGLE = 20;
// Drum radius that makes neighbouring rows touch exactly.
// Rounded so server and browser trig can't disagree in the markup.
const RADIUS =
Math.round(
(ITEM_HEIGHT / 2 / Math.tan((ITEM_ANGLE / 2) * (Math.PI / 180))) * 100
) / 100;
// Rows past ±90° face away; render a few either side of that and no more.
const WINDOW = Math.ceil(90 / ITEM_ANGLE);
const VIEW_HEIGHT = Math.round(RADIUS * 2) + ITEM_HEIGHT / 2;
// A non-looping wheel can be dragged this many rows past either end.
const MAX_OVERSCROLL = 1.2;
const VELOCITY_WINDOW_MS = 80;
const TAP_SLOP = 4;
// Seconds of travel a flick is worth: release speed × COAST = rows coasted.
const COAST = 0.32;
const mod = (n: number, m: number) => ((n % m) + m) % m;
function damp(distance: number, max: number) {
return max * (1 - Math.exp(-distance / max));
}
function hapticTick() {
if (typeof navigator !== "undefined" && "vibrate" in navigator) {
navigator.vibrate(1);
}
}
export interface WheelPickerProps {
columns?: WheelColumn[];
/** Controlled selection, keyed by column id. */
value?: Record<string, string>;
/** Initial selection when uncontrolled. */
defaultValue?: Record<string, string>;
/** Called once a wheel comes to rest on a new option. */
onValueChange?: (value: Record<string, string>) => void;
/** Accessible name for the whole picker. */
label?: string;
className?: string;
}
/**
* An iOS-style drum picker. Each column is a real 3D cylinder: rows are
* placed round it with `rotateX() translateZ()` and the whole drum turns
* with a single transform, so a frame costs one style write per column.
*
* The drum is drawn twice. The bottom copy is muted; the top copy is in full
* color and clipped to the selection band. Text turns dark exactly as it
* crosses the band's edge, the way the native picker does. Hairline ticks
* mark the band's ends.
*/
export default function WheelPicker({
columns = DEFAULT_COLUMNS,
value: valueProp,
defaultValue = DEFAULT_VALUE,
onValueChange,
label = "Time",
className,
}: WheelPickerProps) {
const [internal, setInternal] = useState(defaultValue);
const value = valueProp ?? internal;
// A column settles from a callback made when its spin started. If another
// column changed in the meantime, merging into that render's `value`
// would undo it, so merge into the latest selection instead.
const latestValue = useRef(value);
latestValue.current = value;
const select = (columnId: string, optionValue: string) => {
const current = latestValue.current;
if (current[columnId] === optionValue) {
return;
}
const next = { ...current, [columnId]: optionValue };
latestValue.current = next;
if (valueProp === undefined) {
setInternal(next);
}
onValueChange?.(next);
};
return (
// biome-ignore lint/a11y/useSemanticElements: a fieldset would add a border and legend layout the picker doesn't want.
<div
aria-label={label}
className={cn(
"relative flex select-none justify-center rounded-2xl border border-zinc-200 bg-white px-3 dark:border-zinc-800 dark:bg-zinc-950",
className
)}
role="group"
>
{/* The selection band, shared by every column. */}
<div
aria-hidden="true"
className="pointer-events-none absolute inset-x-2 top-1/2 -translate-y-1/2 rounded-lg bg-zinc-100 dark:bg-zinc-800/70"
style={{ height: ITEM_HEIGHT }}
/>
{/* Hairline ticks either side of the band, like a ruler's pointer. */}
<span
aria-hidden="true"
className="pointer-events-none absolute top-1/2 left-0.5 h-px w-1 -translate-y-1/2 bg-zinc-400 dark:bg-zinc-500"
/>
<span
aria-hidden="true"
className="pointer-events-none absolute top-1/2 right-0.5 h-px w-1 -translate-y-1/2 bg-zinc-400 dark:bg-zinc-500"
/>
{columns.map((column) => (
<WheelColumnView
column={column}
key={column.id}
onSelect={(optionValue) => select(column.id, optionValue)}
selected={value[column.id]}
/>
))}
</div>
);
}
function WheelColumnView({
column,
selected,
onSelect,
}: {
column: WheelColumn;
selected: string | undefined;
onSelect: (value: string) => void;
}) {
const { options, loop = false } = column;
const count = options.length;
const selectedIndex = Math.max(
options.findIndex((option) => option.value === selected),
0
);
const reduceMotion = useReducedMotion();
// Position on the drum in rows. A looping wheel uses an unbounded
// "virtual" index so it can spin forever; the option is index mod count.
const position = useMotionValue(selectedIndex);
const [center, setCenter] = useState(selectedIndex);
const animation = useRef<AnimationPlaybackControls | null>(null);
const pointerType = useRef("mouse");
const drag = useRef<{
id: number;
startY: number;
startPosition: number;
moved: boolean;
samples: { t: number; v: number }[];
} | null>(null);
const columnRef = useRef<HTMLDivElement>(null);
const drum = useTransform(
position,
(p) => `translateZ(${-RADIUS}px) rotateX(${p * ITEM_ANGLE}deg)`
);
const optionAt = (index: number) => options[mod(index, count)];
useMotionValueEvent(position, "change", (p) => {
const rounded = Math.round(p);
if (rounded !== center) {
setCenter(rounded);
if (pointerType.current === "touch") {
hapticTick();
}
}
});
// Follow the selection when it changes from outside (controlled value,
// keyboard, another column re-rendering the parent).
useEffect(() => {
if (drag.current || animation.current) {
return;
}
const current = mod(Math.round(position.get()), count);
if (current === selectedIndex) {
return;
}
// Take the short way round on a looping wheel.
let delta = selectedIndex - current;
if (loop && Math.abs(delta) > count / 2) {
delta -= Math.sign(delta) * count;
}
position.jump(Math.round(position.get()) + delta);
}, [selectedIndex, count, loop, position]);
useEffect(() => () => animation.current?.stop(), []);
const settle = () => {
animation.current = null;
onSelect(optionAt(Math.round(position.get())).value);
};
const clampIndex = (index: number) =>
loop ? index : Math.min(Math.max(index, 0), count - 1);
const goTo = (target: number) => {
animation.current?.stop();
animation.current = null;
if (reduceMotion) {
position.jump(target);
settle();
return;
}
animation.current = animate(position, target, {
type: "spring",
duration: 0.4,
bounce: 0.15,
restDelta: 0.001,
onComplete: settle,
});
};
// Past the ends of a non-looping wheel the drum keeps following the
// finger, but less and less, then springs back on release.
const withOverscroll = (raw: number) => {
if (loop) {
return raw;
}
if (raw < 0) {
return -damp(-raw, MAX_OVERSCROLL);
}
if (raw > count - 1) {
return count - 1 + damp(raw - (count - 1), MAX_OVERSCROLL);
}
return raw;
};
const handlePointerDown = (event: PointerEvent<HTMLDivElement>) => {
if (drag.current) {
return;
}
if (event.pointerType === "mouse" && event.button !== 0) {
return;
}
animation.current?.stop();
animation.current = null;
pointerType.current = event.pointerType;
event.currentTarget.setPointerCapture(event.pointerId);
drag.current = {
id: event.pointerId,
startY: event.clientY,
startPosition: position.get(),
moved: false,
samples: [{ t: event.timeStamp, v: position.get() }],
};
};
const handlePointerMove = (event: PointerEvent<HTMLDivElement>) => {
const current = drag.current;
if (!current || current.id !== event.pointerId) {
return;
}
const dy = event.clientY - current.startY;
if (!current.moved && Math.abs(dy) < TAP_SLOP) {
return;
}
current.moved = true;
const raw = current.startPosition - dy / ITEM_HEIGHT;
position.set(withOverscroll(raw));
current.samples.push({ t: event.timeStamp, v: raw });
while (
current.samples.length > 2 &&
event.timeStamp - current.samples[0].t > VELOCITY_WINDOW_MS
) {
current.samples.shift();
}
};
const handlePointerUp = (event: PointerEvent<HTMLDivElement>) => {
const current = drag.current;
if (!current || current.id !== event.pointerId) {
return;
}
drag.current = null;
if (!current.moved && event.type !== "pointerup") {
// Cancelled before it became a drag: settle where it is.
goTo(clampIndex(Math.round(position.get())));
return;
}
if (!current.moved) {
// A tap: turn to the row under the finger. asin undoes the drum's
// foreshortening, so rows near the edges are hit accurately too.
const rect = event.currentTarget.getBoundingClientRect();
const offsetY = event.clientY - (rect.top + rect.height / 2);
const ratio = Math.max(-1, Math.min(1, offsetY / RADIUS));
const rows = Math.round((Math.asin(ratio) * 180) / Math.PI / ITEM_ANGLE);
goTo(clampIndex(Math.round(position.get()) + rows));
return;
}
const first = current.samples[0];
const last = current.samples.at(-1) ?? first;
const elapsed = (last.t - first.t) / 1000;
// Holding still before letting go is a placement, not a flick.
const paused = event.timeStamp - last.t > VELOCITY_WINDOW_MS;
const velocity = elapsed > 0 && !paused ? (last.v - first.v) / elapsed : 0;
const p = position.get();
const outOfBounds = !loop && (p < 0 || p > count - 1);
if (reduceMotion || outOfBounds || Math.abs(velocity) < 2) {
goTo(clampIndex(Math.round(p)));
return;
}
// A flick spins the drum, slows down, and lands exactly on a row. On a
// non-looping wheel it bounces off the end if it runs out of options.
animation.current?.stop();
// Project where the flick would coast to, land that on a whole row,
// then spring there carrying the release velocity. Critically damped, so
// it decelerates smoothly; past a non-looping end it overshoots slightly
// and settles back, which reads as a bounce.
const target = clampIndex(Math.round(p + velocity * COAST));
animation.current = animate(position, target, {
type: "spring",
velocity,
stiffness: 140,
damping: 24,
restDelta: 0.005,
onComplete: settle,
});
};
// Keyboard steps are instant: they repeat quickly, and a spin per press
// would always be a step behind.
const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
const index = Math.round(position.get());
const moves: Record<string, number> = {
ArrowUp: 1,
ArrowDown: -1,
PageUp: 5,
PageDown: -5,
};
let target: number;
if (event.key === "Home") {
target = index - mod(index, count);
} else if (event.key === "End") {
target = index - mod(index, count) + count - 1;
} else if (event.key in moves) {
target = clampIndex(index + moves[event.key]);
} else {
return;
}
event.preventDefault();
animation.current?.stop();
pointerType.current = "keyboard";
position.jump(target);
settle();
};
// Wheel and trackpad scrolling turn the drum, then it settles on the
// nearest row once the scrolling stops. The listener is attached once and
// reads the latest props through a ref, so a re-render mid-scroll (the
// drum crossing a row) can't drop the pending settle.
const wheel = useRef({ loop, count, goTo, clampIndex });
wheel.current = { loop, count, goTo, clampIndex };
useEffect(() => {
const node = columnRef.current;
if (!node) {
return;
}
let timer: number | undefined;
const onWheel = (event: WheelEvent) => {
event.preventDefault();
const latest = wheel.current;
animation.current?.stop();
animation.current = null;
pointerType.current = "mouse";
const raw = position.get() + (event.deltaY / ITEM_HEIGHT) * 0.4;
position.set(
latest.loop
? raw
: Math.min(Math.max(raw, -0.4), latest.count - 1 + 0.4)
);
window.clearTimeout(timer);
timer = window.setTimeout(() => {
const settled = wheel.current;
settled.goTo(settled.clampIndex(Math.round(position.get())));
}, 120);
};
node.addEventListener("wheel", onWheel, { passive: false });
return () => {
node.removeEventListener("wheel", onWheel);
window.clearTimeout(timer);
};
}, [position]);
const rows: number[] = [];
for (let i = center - WINDOW; i <= center + WINDOW; i++) {
if (loop || (i >= 0 && i < count)) {
rows.push(i);
}
}
return (
<div
aria-label={column.label}
aria-valuemax={count - 1}
aria-valuemin={0}
aria-valuenow={selectedIndex}
aria-valuetext={options[selectedIndex]?.label}
className={cn(
"relative cursor-grab touch-none rounded-lg outline-none active:cursor-grabbing",
"focus-visible:ring-2 focus-visible:ring-zinc-400 focus-visible:ring-inset",
column.className ?? "w-16"
)}
onKeyDown={handleKeyDown}
onLostPointerCapture={handlePointerUp}
onPointerCancel={handlePointerUp}
onPointerDown={handlePointerDown}
onPointerMove={handlePointerMove}
onPointerUp={handlePointerUp}
ref={columnRef}
role="spinbutton"
style={{ height: VIEW_HEIGHT }}
tabIndex={0}
>
{/* The fade sits on an inner layer so the focus ring stays crisp. */}
<div
className="absolute inset-0"
style={{
maskImage:
"linear-gradient(to bottom, transparent, #000 34%, #000 66%, transparent)",
}}
>
<Drum
drum={drum}
optionAt={optionAt}
rowClassName="text-zinc-400 dark:text-zinc-500"
rows={rows}
/>
<Drum
clip
drum={drum}
optionAt={optionAt}
rowClassName="font-medium text-zinc-900 dark:text-zinc-50"
rows={rows}
/>
</div>
</div>
);
}
function Drum({
drum,
rows,
optionAt,
rowClassName,
clip = false,
}: {
drum: MotionValue<string>;
rows: number[];
optionAt: (index: number) => WheelOption;
rowClassName: string;
clip?: boolean;
}) {
return (
<div
aria-hidden="true"
className="pointer-events-none absolute inset-0"
style={{
perspective: 1000,
clipPath: clip
? `inset(calc(50% - ${ITEM_HEIGHT / 2}px) 0 calc(50% - ${ITEM_HEIGHT / 2}px) 0)`
: undefined,
}}
>
<motion.div
className="absolute inset-x-0 top-1/2"
style={{ transform: drum, transformStyle: "preserve-3d" }}
>
{rows.map((index) => (
<div
className={cn(
"absolute inset-x-0 flex items-center justify-center text-xl tabular-nums [backface-visibility:hidden]",
rowClassName
)}
key={index}
style={{
top: -ITEM_HEIGHT / 2,
height: ITEM_HEIGHT,
transform: `rotateX(${-index * ITEM_ANGLE}deg) translateZ(${RADIUS}px)`,
}}
>
{optionAt(index).label}
</div>
))}
</motion.div>
</div>
);
}