Picker Wheel React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Picker Wheel is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import PickerWheel from @/components/ui/picker-wheel.

import { useState } from "react"
import { PickerWheel, PickerWheelField, pickerRange, useDateWheel } from "@/components/ui/picker-wheel"

const hours = pickerRange(8, 19, { pad: 2 })
const minutes = pickerRange(0, 55, { step: 5, pad: 2 })

export function Appointment() {
  const [time, setTime] = useState(["10", "30"])
  const birthday = useDateWheel({ defaultValue: "1990-05-17", locale: "en-US" })

  return (
    <div className="flex flex-col gap-6">
      <PickerWheel aria-label="Date of birth" {...birthday} />
      <PickerWheel
        aria-label="Appointment time"
        loop
        value={time}
        onValueChange={(value) => setTime(value)}
        columns={[
          { id: "hour", label: "h", options: hours },
          { id: "minute", label: "min", options: minutes },
        ]}
      />
      <PickerWheelField
        label="Model year"
        name="year"
        placeholder="Choose the year"
        options={pickerRange(2026, 1990)}
      />
    </div>
  )
}

Props

• columns
  PickerWheelColumnDef[]

  The wheels, left to right: { id, options, label?, width?: "auto" | number, align?: "start" | "center" | "end", loop?, showLabel? }. label names the listbox and shows beside the center row ("h", "min"). Required unless options is set.

• options
  PickerWheelOption[]

  Shortcut for a single column. Each option is { value, label, textValue?, disabled? }; textValue feeds type-to-jump and the field text when the label is not plain text.

• value
  string[]

  One value per column, in column order (controlled). A value that is not an option shows the first enabled option and fires nothing until the user moves.

• defaultValue
  string[]

  The starting values while uncontrolled; defaults to the first enabled option of each column.

• onValueChange
  (value: string[], column: string) => void

  Fires once per settle with every column's value and the id of the column that moved, never per row passed.

• sizedefault "md"
  "sm" | "md" | "lg"

  Row height 36 / 44 / 52px with 15 / 17 / 20px text. md matches the wheels of the time picker's sheet.

• visibleRowsdefault 5
  number

  How many rows show (odd, 3 to 9). The wheel is rowHeight x visibleRows tall: 220px at md with 5 rows.

• perspectivedefault "ios"
  "ios" | "subtle" | "flat"

  How far rows tilt away from the center: 20 / 10 / 0 degrees per row, capped at 55. Opacity falls to 0.35 either way.

• banddefault true
  boolean

  The rounded selection band behind the center row, shared by all columns.

• fadedefault true
  boolean

  Fades the top and bottom rows out with a mask, like the iOS picker.

• showColumnLabelsdefault true
  boolean

  Shows each column's label right after its widest option, beside the center row ("2 h 30 min"). A column's own showLabel wins; date columns from useDateWheel turn it off.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  neutral: a light gray band and foreground text. Other tones tint the band and color the centered row.

• colordefault ""
  string

  Any CSS color; replaces the tone for the band and the centered row.

• disableddefault false
  boolean

  Dims the wheel, stops scrolling and removes the columns from the Tab order.

• loopdefault false
  boolean

  Every column wraps around, so 59 is followed by 00 again. A column's own loop wins; lists shorter than half the window never loop.

• hapticsdefault true
  boolean

  A selection tick each time a new row reaches the center while a finger, a mouse drag or a wheel drives it; never for keys, clicks or outside value changes.

• aria-labeldefault ""
  string

  The name of the group of wheels ("Date of birth"); each column is named by its own label.

• labels
  Partial<PickerWheelLabels>

  Strings: empty "No options", and for the field done "Done", cancel "Cancel", placeholder "Select". Defaults in DEFAULT_PICKER_WHEEL_LABELS.

• classNames
  Partial<Record<"band" | "column" | "option" | "columnLabel", string>>

  Extra classes for the band, each column listbox, each option row and the column labels.

• className
  string

  Extra classes for the root, merged last (width, margins, tone var overrides).

Parts

FAQ

More React mobile components