React Wheel Picker

React Wheel Picker is an iOS-like wheel picker component designed for React applications. It provides a smooth, high-quality selection interface with several key features:

• Natural Scrolling: Supports touch scrolling with smooth inertia, as well as mouse drag and scroll for desktop users.
• Infinite Loop: Supports infinite loop scrolling for continuous selection.
• Unstyled Core: The core logic is unstyled, allowing for complete CSS/style customization to match your application's design.
• Accessibility: Includes full keyboard navigation and type-ahead search capabilities.

The wheel picker is composed of two main components that work in a parent-child relationship:

1. WheelPickerWrapper: The container component. It manages the layout for one or more wheels and provides the overall structure.
2. WheelPicker: The core component that renders an individual wheel. Each WheelPicker includes a 3D perspective container, a scrollable list, a highlight area for the selected option, and a mask for the fade effect.

To create a multi-column picker (like a date picker), wrap multiple WheelPicker components inside a single WheelPickerWrapper.

<WheelPickerWrapper>
  <WheelPicker />
  <WheelPicker />
  <WheelPicker />
</WheelPickerWrapper>

To start the local development environment for the web application, run the development command using your preferred package manager. Once started, the application will be available at http://localhost:3000.

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

You can install the wheel picker using either the shadcn/ui CLI or as a standard React primitive.

shadcn/ui

If you are using shadcn/ui, add the component via the shadcn CLI:

npx shadcn add @ncdai/wheel-picker

Primitives

To use the library as a standard React package, install it via npm:

npm install @ncdai/react-wheel-picker

The WheelPicker supports full keyboard accessibility:

• Vertical Navigation: ArrowUp and ArrowDown scroll the wheel to the next/previous enabled item.
• Picker Switching: In a WheelPickerWrapper group, ArrowLeft and ArrowRight move focus between different pickers.
• Jump to Bounds: Home jumps to the first enabled item; End jumps to the last enabled item (only in non-infinite mode).
• Type-ahead Search: Typing a character will search for the nearest option whose label or textValue matches the character and scroll to it.
• Focus: The component is focusable via Tab and manages its own tabIndex within a group.

To manage multiple WheelPicker components as a single group (e.g., for coordinated keyboard navigation where Arrow keys move focus between pickers), wrap them in a WheelPickerWrapper. This provides the necessary context for the pickers to interact with each other.

import { WheelPicker, WheelPickerWrapper } from '@ncdai/react-wheel-picker';

function MultiPicker() {
  return (
    <WheelPickerWrapper>
      <WheelPicker options={hours} />
      <WheelPicker options={minutes} />
      <WheelPicker options={seconds} />
    </WheelPickerWrapper>
  );
}

The WheelPicker is the primary component for creating a scrollable wheel selection interface. It supports both controlled and uncontrolled modes, infinite scrolling, and keyboard navigation (including type-ahead search).

Basic Usage

import { WheelPicker } from '@ncdai/react-wheel-picker';

const options = [
  { label: 'Option 1', value: '1' },
  { label: 'Option 2', value: '2' },
  { label: 'Option 3', value: '3' },
];

function MyComponent() {
  return (
    <WheelPicker
      options={options}
      onValueChange={(val) => console.log('Selected:', val)}
    />
  );
}