# Inertial Wheel List
An iOS picker drum built on native scroll-snap, with selection derived from scrollTop.
- Demo: https://lab.moumen.dev/components/inertial-wheel-list
- Install: `npx moumenlab add inertial-wheel-list` — or `npx shadcn@latest add https://lab.moumen.dev/r/inertial-wheel-list.json`
- Dependencies: motion
- Registry dependencies: https://lab.moumen.dev/r/lab-theme.json
- Installs to: `components/lab/inertial-wheel-list.tsx`
## Usage
```tsx
"use client";
import WheelList from "./inertial-wheel-list";
// Every quarter hour of the day; the wheel starts on 9:00 AM (index 36).
export const TIMES: string[] = [];
for (let m = 0; m < 24 * 60; m += 15) {
const h = Math.floor(m / 60);
TIMES.push(`${h % 12 === 0 ? 12 : h % 12}:${String(m % 60).padStart(2, "0")} ${h < 12 ? "AM" : "PM"}`);
}
export default function WheelListExample() {
return (
{/* Default: the 3D drum. Selection derives from the scroll position and
commits when the snap settles. */}
console.log(state.settled ? `selected ${state.value}` : "coasting")}
/>
{/* drum={false}: a flat wheel — keeps the scale + fade, drops the rotateX. */}
);
}
```
## Source — `components/lab/inertial-wheel-list.tsx`
```tsx
"use client";
import {
useCallback,
useEffect,
useId,
useLayoutEffect,
useRef,
useState,
type CSSProperties,
type KeyboardEvent,
} from "react";
import { motion, useReducedMotion, useScroll, useTransform, type MotionValue } from "motion/react";
// Inertial wheel list — the iOS picker drum, rebuilt on one principle: the
// SCROLL POSITION IS THE STATE. Nothing is scroll-jacked and no library fakes
// the physics: the scroller is a plain overflow-y list, so the browser (and a
// thumb on a phone) owns momentum, and `scroll-snap-type: y mandatory` +
// `scroll-snap-align: center` land every fling on an item. The selection is
// DERIVED from scrollTop — round(scrollTop / itemHeight) — never stored beside
// it, so the two can't disagree.
//
// The drum look is paint, not layout: motion's `useScroll` tracks the scroller
// and every item derives `rotateX(±38° · t) scale(1.14 → 0.80)` and opacity from
// its distance to the viewport's centre via `useTransform` — motion values
// update outside the React render loop, GPU-composited, no per-frame setState.
// The edge fade is a `mask-image` gradient on the scroller, so items dissolve at
// the rim instead of clipping.
//
// Settling: `scrollend` fires when the snap lands, but not in every engine, so
// a 140ms quiet-timer fallback commits the same selection. Keyboard follows the
// listbox pattern — the scroller is the single tab stop, arrows/Home/End scroll
// to the neighbour (which updates selection because selection IS scroll) and
// aria-activedescendant tracks the centre item. Honours prefers-reduced-motion:
// transforms stay flat, programmatic scrolls jump.
//
// Geometry lives in three CSS custom properties on the root (--wheel-w/-h/-item)
// so the same wheel is fluid on a phone. Fully Tailwind; animation via motion/react.
const WHEEL_VARS = {
"--wheel-w": "14rem",
"--wheel-h": "12.5rem",
"--wheel-item": "2.5rem",
} as CSSProperties;
export interface WheelState {
value: string;
index: number;
count: number;
settled: boolean;
}
interface Metrics {
itemH: number;
centers: number[];
half: number;
}
// Fallback geometry (16px root): item 40px, viewport 200px — used until the
// first real measure lands.
const fallbackMetrics = (count: number): Metrics => ({
itemH: 40,
centers: Array.from({ length: count }, (_, i) => 80 + 40 * i + 20),
half: 100,
});
export default function WheelList({
items,
label = "Pick a value",
initialIndex = 0,
drum = true,
inspect = false,
onStateChange,
}: {
items: string[];
label?: string;
initialIndex?: number;
drum?: boolean;
inspect?: boolean;
onStateChange?: (state: WheelState) => void;
}) {
const scrollerRef = useRef(null);
const settleTimer = useRef(0);
const idBase = useId();
const reduced = useReducedMotion();
const [metrics, setMetrics] = useState(() => fallbackMetrics(items.length));
const [index, setIndex] = useState(initialIndex);
const [settled, setSettled] = useState(true);
const indexRef = useRef(initialIndex);
const metricsRef = useRef(metrics);
metricsRef.current = metrics;
const { scrollY } = useScroll({ container: scrollerRef });
const clampIndex = useCallback(
(i: number) => Math.min(Math.max(i, 0), items.length - 1),
[items.length],
);
function handleScroll() {
// Selection derives from the scroll on every frame; it commits when the
// snap lands (scrollend where the engine has it, the quiet-timer elsewhere).
const scroller = scrollerRef.current;
if (scroller) {
const next = clampIndex(Math.round(scroller.scrollTop / metricsRef.current.itemH));
if (next !== indexRef.current) {
indexRef.current = next;
setIndex(next);
}
}
setSettled(false);
window.clearTimeout(settleTimer.current);
settleTimer.current = window.setTimeout(() => setSettled(true), 140);
}
function handleScrollEnd() {
window.clearTimeout(settleTimer.current);
setSettled(true);
}
function scrollToIndex(i: number, smooth = true) {
const scroller = scrollerRef.current;
if (!scroller) return;
scroller.scrollTo({
top: clampIndex(i) * metricsRef.current.itemH,
behavior: smooth && !reduced ? "smooth" : "auto",
});
}
function handleKeyDown(event: KeyboardEvent) {
const steps: Record = { ArrowUp: -1, ArrowDown: 1, PageUp: -5, PageDown: 5 };
let target: number;
if (event.key in steps) target = indexRef.current + steps[event.key];
else if (event.key === "Home") target = 0;
else if (event.key === "End") target = items.length - 1;
else return;
event.preventDefault();
scrollToIndex(target);
}
// Measure once (and on resize / new items): item height, each centre, and the
// half-viewport — cached so the motion transforms never read layout.
useLayoutEffect(() => {
const scroller = scrollerRef.current;
if (!scroller) return undefined;
const measure = () => {
const options = scroller.querySelectorAll('[role="option"]');
if (!options.length) return;
setMetrics({
itemH: options[0].offsetHeight,
centers: Array.from(options, (el) => el.offsetTop + el.offsetHeight / 2),
half: scroller.clientHeight / 2,
});
};
measure();
const observer = typeof ResizeObserver !== "undefined" ? new ResizeObserver(measure) : null;
observer?.observe(scroller);
return () => observer?.disconnect();
}, [items]);
// Land on the initial value before first paint — no snap animation on load.
useLayoutEffect(() => {
const scroller = scrollerRef.current;
if (scroller) scroller.scrollTop = clampIndex(initialIndex) * metricsRef.current.itemH;
// eslint-disable-next-line react-hooks/exhaustive-deps
}, []);
useEffect(() => () => window.clearTimeout(settleTimer.current), []);
useEffect(() => {
onStateChange?.({ value: items[index], index, count: items.length, settled });
}, [items, index, settled, onStateChange]);
const optionId = (i: number) => `${idBase}-opt-${i}`;
const value = items[index];
return (
{/* The selection lens: a static bar the centred item scrolls through. */}