Wheel picker

Installation

$ npx shadcn@latest add https://goodui.dev/native/r/wheel-picker.json

Then run npx expo install --fix so react-native-gesture-handler, react-native-reanimated match your Expo SDK. Files land in components/goodui-native/wheel-picker.

Usage

import { useState } from "react";
import { WheelPicker, WheelPickerGroup } from "@/components/goodui-native/wheel-picker/wheel-picker";

const hours = Array.from({ length: 24 }, (_, h) => ({ value: h, label: String(h).padStart(2, "0") }));
const minutes = Array.from({ length: 12 }, (_, i) => ({ value: i * 5, label: String(i * 5).padStart(2, "0") }));

export function DepartureTime() {
  const [hour, setHour] = useState(8);
  const [minute, setMinute] = useState(30);
  return (
    <WheelPickerGroup accessibilityLabel="Departure time">
      <WheelPicker options={hours} value={hour} onValueChange={setHour} loop align="right" accessibilityLabel="Hour" />
      <WheelPicker options={minutes} value={minute} onValueChange={setMinute} loop align="left" accessibilityLabel="Minute" />
    </WheelPickerGroup>
  );
}

When to use

Examples

<WheelPicker
  accessibilityLabel="Guests"
  defaultValue={2}
  options={[1, 2, 3, 4, 5, 6].map((n) => ({ value: n, label: `${n} guests`, disabled: n === 5 }))}
  onValueChange={setGuests}
  style={{ width: 160 }}
/>

<WheelPickerGroup size="sm" visibleRows={3}>
  <WheelPicker options={hourOptions} value={h} onValueChange={setH} accessibilityLabel="Hours" />
  <WheelPicker options={[{ value: "h", label: "hours" }]} value="h" accessibilityLabel="Unit" />
  <WheelPicker options={minuteOptions} value={m} onValueChange={setM} loop accessibilityLabel="Minutes" />
</WheelPickerGroup>

API reference

Motion and haptics

• •Rows are placed on a cylinder as tall as the wheel: a row's angle is its arc distance from the center, it moves to r·sin(angle) and tilts by that angle in perspective, fading with cos(angle). The center row is in the foreground color and rows turn secondary as they leave it.
• •Dragging moves the wheel 1:1 with the finger; past either end (without loop) it rubber-bands with growing resistance.
• •Release projects the fling 0.3 s ahead, picks the nearest enabled row and glides there on an ease-out curve whose starting speed matches the finger, so it decelerates naturally. Slow releases and taps settle on the smooth spring.
• •Tapping a row above or below the center turns the wheel to it.
• •Value changes from outside turn the wheel on the smooth spring (to the nearest copy of the row when looping).
• •Reduced motion: release and taps settle with a 120 ms timing without the long glide, and outside changes jump. The 3D layout itself is static and stays.

• •Haptic: select for every row that passes the center while the person drags, flings, taps, scrolls or uses keys; changes made from outside are silent.
• •Haptic: haptic={false} silences a wheel.

• •Position, perspective and colors run on the UI thread; onValueChange fires once when the wheel comes to rest, never per frame.
• •Up to 48 options mount every row. Longer lists (years, for example) mount only a window of rows around the center that moves every six rows.
• •Callers may rebuild options every render: the gesture is only recreated when the pattern of disabled rows changes.

Accessibility

• •Each wheel is one adjustable element: swipe up or down with VoiceOver or TalkBack (increment and decrement actions labelled Next and Previous) to move one row; the value is the row label or its accessibilityLabel.
• •WheelPickerGroup is named with accessibilityLabel and is a group on the web; name every column with its own accessibilityLabel (Hour, Minute).
• •On the web a wheel is a focusable slider with aria-valuenow (row number), aria-valuemin, aria-valuemax and aria-valuetext (the label). Arrow Down or Right moves to the next row, Up or Left to the previous, Page Up and Page Down move five rows, Home and End jump to the first and last enabled row.
• •The drawn rows are decoration: hidden from assistive tech (inert on the web), so only the wheel and its value are read. The selected row is always in the foreground color on the band; the dimmed neighbours are 3D context and do not carry information of their own.
• •Disabled rows are skipped by every input: drag, fling, tap, mouse wheel and keys.
• •The wheel is as tall as its rows (32 or 36 pt each); the whole wheel is the touch target.

Notes for AI

Related