WheelPickerNew

Import

import { WheelPicker } from 'heroui-native-pro';

Anatomy

<WheelPicker items={[...]}>
  <WheelPicker.Indicator />
  <WheelPicker.Mask />
</WheelPicker>

• WheelPicker: Root container. Manages controllable selection through value / defaultValue / onValueChange, owns the shared scroll offset, and renders a data-driven scrolling list of rows. Cascades animation settings to children and auto-renders a default indicator when no compound children are passed.
• WheelPicker.Item: Animated row container. Auto-rendered for every option, or used as the outer element inside a custom renderItem. When no children are provided, renders WheelPicker.ItemLabel with the option's label. Tapping a row scrolls the wheel to focus it.
• WheelPicker.ItemLabel: Default label primitive. Used by the auto-fallback inside WheelPicker.Item; reuse inside a custom renderItem to keep the default label styling.
• WheelPicker.Indicator: Optional selection band rendered absolutely at the center of the viewport. Purely visual — selection logic lives on the root.
• WheelPicker.Mask: Optional top / bottom fade overlays that soften the wheel into the surrounding background.

Usage

Basic usage

Pass a list of { value, label } items and bind value / onValueChange. The root renders a default indicator when no compound children are present.

const [year, setYear] = useState(1995);

<WheelPicker value={year} onValueChange={setYear} items={YEAR_ITEMS} />;

With mask

Add a WheelPicker.Mask for top / bottom fade overlays. Explicit children replace the auto-rendered indicator, so include WheelPicker.Indicator too.

<WheelPicker value={year} onValueChange={setYear} items={YEAR_ITEMS}>
  <WheelPicker.Indicator />
  <WheelPicker.Mask />
</WheelPicker>

Uncontrolled

Use defaultValue to seed the initial selection without managing external state.

<WheelPicker defaultValue={1995} items={YEAR_ITEMS} onValueChange={...} />

Item height and visible count

Customize row height and the number of visible rows. visibleCount must be odd so a single row sits centered on the indicator.

<WheelPicker
  items={SLOT_ITEMS}
  defaultValue="13:30"
  itemHeight={56}
  visibleCount={5}
/>

Custom item render

Pass renderItem to compose custom content per row. Use WheelPicker.Item as the outer wrapper to preserve sizing and tap-to-focus behavior.

<WheelPicker
  value={reminder}
  onValueChange={setReminder}
  items={REMINDER_TYPE_ITEMS}
  renderItem={({ item, isSelected }) => (
    <WheelPicker.Item className="flex-row items-center justify-center gap-3">
      <ReminderIcon
        value={item.value}
        colorClassName={isSelected ? 'accent-accent' : 'accent-muted'}
      />
      <WheelPicker.ItemLabel className="font-medium">
        {item.label}
      </WheelPicker.ItemLabel>
    </WheelPicker.Item>
  )}
>
  <WheelPicker.Indicator />
  <WheelPicker.Mask />
</WheelPicker>

Custom indicator

Style the selection band via classNames on WheelPicker.Indicator, or pass any children for decorative content rendered inside the highlight slot (patterns, gradients, icons). Pair with overflow-hidden on the highlight when the children should be clipped to the rounded corners.

<WheelPicker items={DURATION_ITEMS} defaultValue={25}>
  <WheelPicker.Indicator
    classNames={{
      wrapper: 'px-2',
      highlight: 'bg-accent-soft border border-accent/15 overflow-hidden',
    }}
  >
    <MyIndicatorPattern />
  </WheelPicker.Indicator>
  <WheelPicker.Mask />
</WheelPicker>

Custom mask color

Override the fade color when the wheel sits on a non-background surface. Combine with height (number or percentage) to control how far the fade extends.

const overlayColor = useThemeColor('overlay');

<WheelPicker items={TIME_ITEMS} defaultValue="09:00">
  <WheelPicker.Indicator />
  <WheelPicker.Mask color={overlayColor} height="75%" />
</WheelPicker>;

Custom animation

Tune the per-item [edge, center] opacity, scale, and label color ranges. The label color animation is always active (defaulting to theme [foreground, accent-soft-foreground]) — text-* color classes on classNames.itemLabel are overridden by the animated value.

<WheelPicker
  items={REMINDER_TYPE_ITEMS}
  defaultValue="notification"
  animation={{
    opacity: { value: [0.4, 1] },
    scale: { value: [0.75, 1] },
    labelColor: { value: ['#888', '#000'] },
  }}
/>

Disabled

Block interaction and dim the wheel with isDisabled.

<WheelPicker items={YEAR_ITEMS} defaultValue={1995} isDisabled />

Programmatic scroll

Use the ref to drive the selection imperatively. scrollToValue finds the matching row via Object.is equality and is a no-op when the value is not in items.

const ref = useRef<WheelPickerRootRef>(null);

<WheelPicker ref={ref} items={YEAR_ITEMS} defaultValue={1995} />;

ref.current?.scrollToValue(2000);
ref.current?.scrollToIndex({ index: 0, animated: false });

Example

import { WheelPicker } from 'heroui-native-pro';
import { useState } from 'react';
import { Text, View } from 'react-native';

const CURRENT_YEAR = new Date().getFullYear();
const YEAR_ITEMS = Array.from({ length: 80 }, (_, index) => {
  const year = CURRENT_YEAR - 18 - index;
  return { value: year, label: String(year) };
});

export default function BirthYearPicker() {
  const [year, setYear] = useState(1995);

  return (
    <View className="flex-1 items-center justify-center px-5">
      <View className="items-center gap-6">
        <View className="items-center gap-1">
          <Text className="text-xs text-muted uppercase tracking-wider">
            Date of birth
          </Text>
          <Text className="text-2xl font-semibold text-foreground tabular-nums">
            {year}
          </Text>
        </View>
        <View className="w-[200px]">
          <WheelPicker
            value={year}
            onValueChange={setYear}
            items={YEAR_ITEMS}
            classNames={{ itemLabel: 'tabular-nums' }}
          >
            <WheelPicker.Indicator />
            <WheelPicker.Mask />
          </WheelPicker>
        </View>
      </View>
    </View>
  );
}

API Reference

WheelPicker

WheelPickerOption

Single picker entry rendered as a row in the wheel.

WheelPickerRenderItemInfo

Argument passed to renderItem.

ElementSlots<WheelPickerRootSlots>

The item slot animates opacity and transform (scale) for distance-based fade and scale. These properties cannot be overridden via className; use the animation prop to customize, or animation="disabled" to remove them entirely.

styles

WheelPickerRootAnimation

Animation configuration for the per-item opacity, scale, and (optionally) label color interpolation. Can be:

• false or "disabled": Disable per-item fade, scale, and label color (rows snap without interpolation)
• "disable-all": Disable the wheel's animations and cascade disable-all to animated descendants
• true or undefined: Use default animations
• object: Custom animation configuration

WheelPickerImperativeMethods

Exposed via the root ref on top of the underlying View ref.

WheelPicker.Indicator

ElementSlots<WheelPickerIndicatorSlots>

styles

WheelPicker.Mask

ElementSlots<WheelPickerMaskSlots>

styles

WheelPicker.Item

WheelPicker.Item is the per-row animated container. When no children are provided, it auto-renders <WheelPicker.ItemLabel>{item.label}</WheelPicker.ItemLabel>. Tapping the row scrolls the wheel to focus it; a consumer onPress runs first.

The row container animates opacity and transform (scale) for distance-based fade and scale. These properties cannot be overridden via className; use the animation prop on the root to customize, or animation="disabled" to remove them entirely.

WheelPicker.ItemLabel

Hooks

useWheelPicker

Hook to access the WheelPicker root context. Must be used within a WheelPicker component.

import { useWheelPicker } from 'heroui-native-pro';

const { itemHeight, visibleCount, scrollY, isDisabled } = useWheelPicker();

Returns: WheelPickerContextValue

useWheelPickerItem

Hook to access the per-row item context. Must be used within a WheelPicker.Item, WheelPicker.ItemLabel, or any component rendered inside a custom renderItem. The context erases the generic to unknown; cast at the call site (as WheelPickerItemRenderProps<MyType>) when you need strict typing on item.value.

import { useWheelPickerItem } from 'heroui-native-pro';

const { item, index, isSelected, absDistance } = useWheelPickerItem();

Use absDistance together with useAnimatedStyle / useAnimatedProps to build your own row-content animations (icons, badges, halos, indicators, etc.) without recomputing distance math yourself.

Returns: WheelPickerItemRenderProps