WheelPicker

Scrollable wheel picker for selecting from a list of options with snap-to-item behavior.

iOSAndroid

Preview WheelPicker on your device

Scan with Expo Go

Download Expo Go, then scan the QR code to preview native components.

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-wheel-picker

Usage

import { WheelPicker } from '@/components/docyrus-native/wheel-picker';

const options = [
  { label: 'Red', value: 'red' },
  { label: 'Green', value: 'green' },
  { label: 'Blue', value: 'blue' },
];

<WheelPicker
  options={options}
  value={selected}
  onChange={(val) => setSelected(val)}
/>

API Reference

Prop	Type	Default	Description
`options`	`WheelPickerOption[]`	—	Array of selectable options
`value`	`string`	—	Currently selected value
`onChange`	`(value: string) => void`	—	Selection change handler
`itemHeight`	`number`	`44`	Height of each option row in pixels
`visibleItems`	`number`	`5`	Number of visible items in the wheel
`disabled`	`boolean`	`false`	Disable scrolling and selection (dimmed)
`accessibilityLabel`	`string`	—	Screen-reader label; the selected option's label is exposed as the accessibility value
`className`	`string`	—	Additional CSS classes
`style`	`ViewStyle`	—	Container style

Selection commits when scrolling settles (snap) or when an option is tapped. Changing value from outside scrolls the wheel to it, and landing on a disabled option snaps back to the current selection. WheelPicker powers the month / year jump sheet of DayPicker (captionLayout="dropdown").

WheelPickerOption

Prop	Type	Description
`label`	`string`	Display text
`value`	`string`	Option value
`disabled`	`boolean`	Whether the option is disabled
`icon`	`string`	Image URI for an icon
`initials`	`string`	Initials badge shown when there is no `icon`

Components

Component	Description
`WheelPicker`	Snap-scrolling wheel picker

Type Exports

Type	Description
`WheelPickerProps`	Props for WheelPicker component
`WheelPickerOption`	Option item configuration