React Wheel Picker

https://react-wheel-picker.chanhdai.com/docs
Admin
An iOS-like wheel picker component for React applications, featuring smooth inertia scrolling and...
Tokens:2,186
Snippets:16
Trust Score:7.8
Update:9 months ago
Show doc for...
Tokens:
Raw
### Install React Wheel Picker

Source: https://react-wheel-picker.chanhdai.com/docs/getting-started

Installs the React Wheel Picker component using pnpm, yarn, or npm. This is the initial step to integrate the component into your project.

```bash
pnpm dlx shadcn add @ncdai/wheel-picker
```

--------------------------------

### Basic React Wheel Picker Usage

Source: https://react-wheel-picker.chanhdai.com/docs/getting-started

Provides a fundamental example of how to use the `WheelPicker` component with an array of options and state management for the selected value. It demonstrates controlled mode usage.

```jsx
import { useState } from "react";
import {
  WheelPicker,
  WheelPickerWrapper,
  type WheelPickerOption,
} from "@/components/wheel-picker";

const options: WheelPickerOption[] = [
  {
    label: "Next.js",
    value: "nextjs",
  },
  {
    label: "Vite",
    value: "vite",
  },
  // ...
];
 
export function WheelPickerDemo() {
  const [value, setValue] = useState("nextjs");
 
  return (
    <WheelPickerWrapper>
      <WheelPicker options={options} value={value} onValueChange={setValue} />
    </WheelPickerWrapper>
  );
}
```

--------------------------------

### Configure shadcn MCP Server (Optional)

Source: https://react-wheel-picker.chanhdai.com/docs/getting-started

Configures the shadcn MCP server to enable AI assistants to understand your component registry. This is an optional step for enhanced developer experience.

```bash
pnpm dlx shadcn mcp init
```

--------------------------------

### Data Attributes for Styling

Source: https://react-wheel-picker.chanhdai.com/docs/getting-started

Data attributes available for CSS styling of the wheel picker components.

```APIDOC
## Data Attributes

The following data attributes are available for CSS styling:

| Attribute               | Element                 | Description                                    |
| ----------------------- | ----------------------- | ---------------------------------------------- |
| `[data-rwp-wrapper]`    | Wrapper                 | Applied to `WheelPickerWrapper`                |
| `[data-rwp]`            | Picker                  | Applied to `WheelPicker` root element          |
| `[data-rwp-options]`    | Options container       | Applied to the options list container          |
| `[data-rwp-option]`     | Option item             | Applied to each option item in the wheel       |
| `[data-rwp-highlight-wrapper]` | Highlight wrapper         | Applied to the highlight area wrapper          |
| `[data-rwp-highlight-list]`  | Highlight list          | Applied to the highlight list container        |
| `[data-rwp-highlight-item]`  | Highlight item          | Applied to the highlighted option item         |
| `[data-rwp-focused]`    | Highlight wrapper       | Present on `[data-rwp-highlight-wrapper]` when the picker is focused |
```

--------------------------------

### React Wheel Picker Anatomy

Source: https://react-wheel-picker.chanhdai.com/docs/getting-started

Demonstrates the basic structure of the React Wheel Picker component, showing the parent wrapper and individual picker elements.

```jsx
<WheelPickerWrapper>
  <WheelPicker />
  <WheelPicker />
  <WheelPicker />
</WheelPickerWrapper>
```

--------------------------------

### Import React Wheel Picker Components

Source: https://react-wheel-picker.chanhdai.com/docs/getting-started

Imports the necessary components and types for the React Wheel Picker from the library. This is required before using the components in your application.

```typescript
import {
  WheelPicker,
  WheelPickerWrapper,
  type WheelPickerOption,
} from "@/components/wheel-picker";
```

--------------------------------

### WheelPicker Types

Source: https://react-wheel-picker.chanhdai.com/docs/getting-started

TypeScript types for WheelPicker options and class names.

```APIDOC
## Types

### `WheelPickerValue`
```typescript
type WheelPickerValue = string | number;
```

### `WheelPickerOption<T>`
```typescript
type WheelPickerOption<T extends WheelPickerValue = string> = {
  /** Value that will be returned when this option is selected */
  value: T;
  /** The content displayed for this option */
  label: ReactNode;
  /** Optional text for type-ahead search (useful when label is a ReactNode). Defaults to label if string, otherwise value. */
  textValue?: string;
};
```

### `WheelPickerClassNames`
```typescript
type WheelPickerClassNames = {
  /** Class name for individual option items */
  optionItem?: string;
  /** Class name for the wrapper of the highlighted area */
  highlightWrapper?: string;
  /** Class name for the highlighted item */
  highlightItem?: string;
};
```
```

--------------------------------

### WheelPicker Props

Source: https://react-wheel-picker.chanhdai.com/docs/getting-started

Props available for the WheelPicker component.

```APIDOC
## WheelPicker Props

### Description
Props for the `WheelPicker` component.

### Parameters
#### Request Body
- **options** (WheelPickerOption<T>[]) - Required - Array of options to display in the wheel
- **value** (T) - Optional - Current value of the picker (controlled mode). Type matches the option values (string or number)
- **defaultValue** (T) - Optional - Default value of the picker (uncontrolled mode). Type matches the option values (string or number)
- **onValueChange** ((value: T) => void) - Optional - Callback fired when the selected value changes. Receives the selected option's value
- **infinite** (boolean) - Optional - Enable infinite scrolling. Defaults to `false`.
- **visibleCount** (number) - Optional - Number of options visible on the wheel (must be multiple of 4). Defaults to `20`.
- **dragSensitivity** (number) - Optional - Sensitivity of the drag interaction (higher = more sensitive). Defaults to `3`.
- **scrollSensitivity** (number) - Optional - Sensitivity of the scroll interaction (higher = more sensitive). Defaults to `5`.
- **optionItemHeight** (number) - Optional - Height (in pixels) of each item in the picker list. Defaults to `30`.
- **classNames** (WheelPickerClassNames) - Optional - Custom class names for styling
```

--------------------------------

### WheelPickerWrapper Props

Source: https://react-wheel-picker.chanhdai.com/docs/getting-started

Props available for the WheelPickerWrapper component.

```APIDOC
## WheelPickerWrapper Props

### Description
Props for the `WheelPickerWrapper` component.

### Parameters
#### Request Body
- **className** (string) - Optional - CSS class name for wrapper
- **children** (ReactNode) - Required - `WheelPicker` components
```

--------------------------------

### WheelPickerOption Type Definition

Source: https://react-wheel-picker.chanhdai.com/docs/getting-started

Defines the TypeScript type for a single option in the wheel picker. Each option has a required `value` and `label`, and an optional `textValue` for searching.

```typescript
type WheelPickerValue = string | number;

type WheelPickerOption<T extends WheelPickerValue = string> = {
  /** Value that will be returned when this option is selected */
  value: T;
  /** The content displayed for this option */
  label: ReactNode;
  /** Optional text for type-ahead search (useful when label is a ReactNode). Defaults to label if string, otherwise value. */
  textValue?: string;
};
```

--------------------------------

### WheelPickerClassNames Type Definition

Source: https://react-wheel-picker.chanhdai.com/docs/getting-started

Defines the TypeScript type for custom class names that can be applied to various parts of the `WheelPicker` component for styling purposes.

```typescript
type WheelPickerClassNames = {
  /** Class name for individual option items */
  optionItem?: string;
  /** Class name for the wrapper of the highlighted area */
  highlightWrapper?: string;
  /** Class name for the highlighted item */
  highlightItem?: string;
};
```
Tokens:
Raw