wheel picker.md

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>
  );
}