react-native-drum-picker

A smooth cross-platform native iOS-style drum/wheel picker for React Native (Fabric / New Architecture).

Preview

iOS preview coming soon — see the ios-build CI job for validation status.

Features

Android native implementation (Kotlin + RecyclerView)
iOS native implementation (Swift + UIPickerView)
iOS-style wheel / drum picker with smooth snapping
Center selection indicator (optional)
Transparent background by default
Custom text colors and sizes
TypeScript API
Flexible DateDrumPicker wrapper (day / month / year columns)
Fabric View / New Architecture

Installation

yarn add react-native-drum-picker

npm install react-native-drum-picker

This package includes native Android and iOS code. Rebuild your app after installing:

npx pod-install
npx react-native run-ios
npx react-native run-android

Platform support

Platform	Status
Android	Supported
iOS	Supported
Web	Read-only preview stub (`DrumPicker.tsx`); ref API works, no native wheel

Requires React Native 0.76+ with the New Architecture enabled.

Compatibility

Environment	Status
React Native New Architecture	Required
Fabric	Required
Android	Supported
iOS	Supported
iOS Old Architecture (Paper)	Not supported — Fabric required
Expo Go	Not supported (native library)
Expo SDK 54 + dev build / prebuild	Tested
`react-native-screens` navigation	Tested (use 0.1.4+ for detach safety)

Tested with

Tool	Version
Expo SDK	54
React Native	0.81.5, 0.85.0 (example app)
New Architecture	enabled
Android	emulator / device

Intended range: react-native >= 0.76 with New Architecture. The package is actively tested on RN 0.81.x / 0.85.x. Older 0.76–0.80 may work but are not CI-guaranteed.

This package is an Android Fabric View library. Use a development build or expo run:android after expo prebuild — not Expo Go.

React Native 0.81+ event dispatch

If Android Kotlin compile fails with No value passed for parameter 'uiManagerType', upgrade to 0.1.3+ (Fabric UIManagerType.FABRIC).

Basic usage

import { DrumPicker } from 'react-native-drum-picker';

export function Example() {
  return (
    <DrumPicker
      items={['Mon 7 Sep', 'Tue 8 Sep', 'Wed 9 Sep']}
      selectedIndex={1}
      itemHeight={44}
      visibleItemCount={5}
      onChange={(event) => {
        console.log(event.nativeEvent.index, event.nativeEvent.value);
      }}
      style={{ width: 150, height: 220 }}
    />
  );
}

Layout defaults (0.1.5+)

The JS wrapper applies minWidth: 64 and, unless you use flex or pass height / minHeight, height: itemHeight * visibleItemCount (default 220). Native Android also sets matching minimumWidth / minimumHeight.

For production layouts, still pass explicit dimensions:

style={{ width: 120, height: itemHeight * visibleItemCount }}

In __DEV__, a one-time warning is logged if neither height nor flex sizing is provided.

Examples

Basic picker

Time picker (hour · minute)

const hours = Array.from({ length: 24 }, (_, i) => String(i).padStart(2, '0'));
const minutes = Array.from({ length: 60 }, (_, i) =>
  String(i).padStart(2, '0')
);

<View style={{ flexDirection: 'row', alignItems: 'center' }}>
  <DrumPicker items={hours} style={{ width: 72, height: 220 }} />
  <DrumPicker items={minutes} style={{ width: 72, height: 220 }} />
</View>;

Height / weight row (onboarding style)

<View style={{ flexDirection: 'row', alignItems: 'center' }}>
  <DrumPicker items={heightsCm} style={{ width: 90, height: 220 }} />
  <DrumPicker items={weightsKg} style={{ width: 96, height: 220 }} />
</View>

Controlled `selectedIndex`

const [index, setIndex] = useState(1);

<DrumPicker
  items={items}
  selectedIndex={index}
  onChange={(e) => setIndex(e.nativeEvent.index)}
  style={{ width: 120, height: 220 }}
/>;

`onChange` and expensive side effects

Native emits onChange when the wheel snaps to idle and the centered index changes (duplicate indices are ignored). Use it for UI state. For AsyncStorage, APIs, or analytics, debounce in your app:

const save = useMemo(() => {
  let t: ReturnType<typeof setTimeout> | undefined;
  return (value: string) => {
    if (t) clearTimeout(t);
    t = setTimeout(() => {
      // persist value
    }, 300);
  };
}, []);

<DrumPicker onChange={(e) => save(e.nativeEvent.value)} ... />

Live sync between pickers

Use onValueChanging to update a preview while the user is still scrolling — before they lift their finger:

const [previewIndex, setPreviewIndex] = useState(1);

<DrumPicker
  items={['AM', 'PM']}
  onValueChanging={({ nativeEvent }) => {
    setPreviewIndex(nativeEvent.index);
  }}
  onChange={({ nativeEvent }) => {
    setPreviewIndex(nativeEvent.index);
  }}
/>;

onValueChanging can fire many times per second while the wheel moves. Keep the handler light; for UI updates prefer a ref or debounce/requestAnimationFrame instead of heavy setState on every tick. Use onChange for the final committed value.

See the example app (example/src/App.tsx) for basic, time, height/weight, date, controlled, and debounced demos.

Imperative ref API

Control the picker programmatically using a ref. scrollToIndex / scrollToValue default to animated: true and invoke onChange when the selection changes (so controlled selectedIndex stays in sync). withVirtualized forwards the same DrumPickerRef using real list indices.

import { useRef } from 'react';
import { Button } from 'react-native';
import { DrumPicker, type DrumPickerRef } from 'react-native-drum-picker';

const months = ['Jan', 'Feb', 'Mar', 'Jun'];

function MyPicker() {
  const ref = useRef<DrumPickerRef>(null);

  return (
    <>
      <DrumPicker
        ref={ref}
        items={months}
        onChange={({ nativeEvent }) => console.log(nativeEvent.value)}
      />
      <Button
        title="Jump to June"
        onPress={() => ref.current?.scrollToValue('Jun')}
      />
      <Button
        title="Reset to first"
        onPress={() => ref.current?.scrollToIndex(0, { animated: true })}
      />
    </>
  );
}

DateDrumPicker ref — "Today" button

import { useRef, useState } from 'react';
import { Button } from 'react-native';
import {
  DateDrumPicker,
  type DateDrumPickerRef,
  type DateDrumPickerValue,
} from 'react-native-drum-picker';

function DateWithToday() {
  const [date, setDate] = useState<DateDrumPickerValue>({
    day: 1,
    month: 1,
    year: 2026,
  });
  const today = new Date();
  const dateRef = useRef<DateDrumPickerRef>(null);

  return (
    <>
      <DateDrumPicker
        ref={dateRef}
        mode="day-month-year"
        value={date}
        onChange={setDate}
      />
      <Button
        title="Today"
        onPress={() =>
          dateRef.current?.scrollToDate(
            {
              day: today.getDate(),
              month: today.getMonth() + 1,
              year: today.getFullYear(),
            },
            { animated: true }
          )
        }
      />
    </>
  );
}

DrumPickerRef API

Method	Description
`scrollToIndex(index, options?)`	Scroll to index. Clamped to valid range.
`scrollToValue(value, options?)`	Scroll to first matching value. No-op if not found.
`getCurrentIndex()`	Returns current selected index.
`getCurrentValue()`	Returns current selected value string.

DateDrumPickerRef API

Method	Description
`scrollToDate(date, options?)`	Scroll columns to given date. Partial updates supported. Clamps invalid days and calls `onChange` when set.
`getCurrentDate()`	Returns clamped `{ day, month, year }` of current selection.

PickerGroup - synchronize multiple pickers

Connect multiple DrumPickers so they can react to each other:

import { useState } from 'react';
import { View } from 'react-native';
import {
  DrumPicker,
  usePickerGroup,
  usePickerGroupChangedEffect,
  usePickerGroupChangingEffect,
} from 'react-native-drum-picker';

const HOURS = Array.from({ length: 24 }, (_, i) => String(i).padStart(2, '0'));
const MINUTES = [
  '00',
  '05',
  '10',
  '15',
  '20',
  '25',
  '30',
  '35',
  '40',
  '45',
  '50',
  '55',
];

function TimePickerGroup() {
  const group = usePickerGroup();
  const [time, setTime] = useState({ hour: 0, minute: 0 });

  usePickerGroupChangedEffect(group, ({ pickerName, index }) => {
    setTime((prev) => ({ ...prev, [pickerName]: index }));
  });

  usePickerGroupChangingEffect(group, ({ pickerName, value }) => {
    console.log(`${pickerName} is at ${value}`);
  });

  return (
    <View style={{ flexDirection: 'row' }}>
      <DrumPicker
        pickerGroup={group}
        pickerName="hour"
        items={HOURS}
        onChange={() => {}}
      />
      <DrumPicker
        pickerGroup={group}
        pickerName="minute"
        items={MINUTES}
        onChange={() => {}}
      />
    </View>
  );
}

PickerGroup API

Export	Description
`usePickerGroup()`	Creates a group handle. Call once per component.
`usePickerGroupChangedEffect(group, cb)`	Fires when any picker settles.
`usePickerGroupChangingEffect(group, cb)`	Fires on every scroll tick.
`group.getState()`	Snapshot of all current picker values.

DrumPicker group props

Prop	Type	Description
`pickerGroup`	`PickerGroupHandle`	Group from `usePickerGroup()`
`pickerName`	`string`	Unique name within the group

Custom item rendering

Use renderItem to replace the default text label with your own React UI:

import { DrumPicker } from 'react-native-drum-picker';
import { Text, View } from 'react-native';

const countries = [
  { label: 'Uzbekistan', value: 'UZ', flag: '🇺🇿' },
  { label: 'Russia', value: 'RU', flag: '🇷🇺' },
  { label: 'USA', value: 'US', flag: '🇺🇸' },
];

<DrumPicker
  items={countries}
  renderItem={({ item, isSelected }) => (
    <View style={{ flexDirection: 'row', gap: 8 }}>
      <Text style={{ fontSize: 24 }}>{item.flag}</Text>
      <Text
        style={{
          fontSize: 18,
          color: isSelected ? '#000' : '#999',
          fontWeight: isSelected ? '600' : '400',
        }}
      >
        {item.label}
      </Text>
    </View>
  )}
  onChange={({ nativeEvent }) => console.log(nativeEvent.value)}
/>;

renderItem info object

Field	Type	Description
`item`	`T`	Raw item from `items`
`label`	`string`	Display label string
`index`	`number`	Index in `items`
`isSelected`	`boolean`	Whether the row is centered

Performance note: keep renderItem lightweight. It can rerender frequently during wheel movement. For complex rows, wrap heavy subtrees with React.memo and pass a stable renderer via useCallback.

const Row = React.memo(function Row({
  flag,
  label,
  isSelected,
}: {
  flag: string;
  label: string;
  isSelected: boolean;
}) {
  return (
    <View style={{ flexDirection: 'row', gap: 8 }}>
      <Text>{flag}</Text>
      <Text style={{ color: isSelected ? '#111' : '#999' }}>{label}</Text>
    </View>
  );
});

const renderCountry = useCallback(
  ({ item, isSelected }) => (
    <Row flag={item.flag} label={item.label} isSelected={isSelected} />
  ),
  []
);

DateDrumPicker

Higher-level date columns (TypeScript only). Renders wheels only — no built-in titles; add labels in your app if needed.

import { useState } from 'react';
import { DateDrumPicker } from 'react-native-drum-picker';

export function DateExample() {
  const [date, setDate] = useState({ day: 21, month: 5, year: 2026 });

  return (
    <DateDrumPicker mode="day-month-year" value={date} onChange={setDate} />
  );
}

<DateDrumPicker
  mode="month-year"
  monthFormat="long"
  minYear={2020}
  maxYear={2035}
  value={{ month: 5, year: 2026 }}
  onChange={(value) => console.log(value)}
/>

Controlled: pass value and update in onChange.
Uncontrolled: omit value; internal state updates and onChange still fires.

Day count follows month/year (e.g. February has 28/29 days).

Date range constraints

import { useState } from 'react';
import {
  DateDrumPicker,
  type DateDrumPickerValue,
} from 'react-native-drum-picker';

function BookingDatePicker() {
  const [bookingDate, setBookingDate] = useState<DateDrumPickerValue>({});
  const today = new Date();
  const nextYear = new Date();
  nextYear.setFullYear(today.getFullYear() + 1);

  return (
    <DateDrumPicker
      mode="day-month-year"
      minDate={{
        day: today.getDate(),
        month: today.getMonth() + 1,
        year: today.getFullYear(),
      }}
      maxDate={{
        day: nextYear.getDate(),
        month: nextYear.getMonth() + 1,
        year: nextYear.getFullYear(),
      }}
      value={bookingDate}
      onChange={setBookingDate}
    />
  );
}

minDate / maxDate take precedence over minYear / maxYear when both are set.

onValueChanging, if used, receives the column key first: (column, event) => … where column is 'day' | 'month' | 'year'. Event nativeEvent.index uses calendar indices (month 1–12 → index 0–11; day uses day-of-month minus 1).

withVirtualized

For large item lists (cities, timezones, country codes), wrap DrumPicker with withVirtualized to render only items near the visible window:

import { DrumPicker, withVirtualized } from 'react-native-drum-picker';

const VirtualizedDrumPicker = withVirtualized(DrumPicker);

const CITIES = ['Tashkent', 'Moscow', 'London' /* ... */]; // 1000+ items

<VirtualizedDrumPicker
  items={CITIES}
  selectedIndex={selectedIndex}
  windowSize={20} // items above + below visible area (default: 20)
  onChange={({ nativeEvent }) => setIndex(nativeEvent.index)}
/>;

windowSize controls the render buffer. Higher = smoother fast flings, higher memory. Default of 20 works for most cases.

Optional windowRecenterDebounceMs (default 100) debounces slice recentering when you reach the first or last row of the current window — this prevents scroll feedback loops during fast flings on large lists.

Platforms: iOS and Android only (wrap DrumPicker from the package — not web). The native wheel always receives a small sliced items array on both platforms.

Requirements: each entry in items must be a unique string. Duplicate labels break index recovery during slice swaps and on iOS tap hit-testing.

Not intended for DateDrumPicker (small fixed column lists).

onValueChanging is supported: indices are remapped to the full list (same as onChange), so live preview works on large lists.

Circular scroll

Enable infinite looping scroll - when user scrolls past the last item it wraps to the first:

// Minutes: 58 -> 59 -> 00 -> 01
<DrumPicker
  circular
  items={minutes}
  onChange={({ nativeEvent }) => setMinute(nativeEvent.index)}
/>

// Combine with TimeDrumPicker
<TimeDrumPicker circular />

Best for: hours, minutes, seconds, days of week, months. Not recommended for: years, long lists (cities, countries).

Note: circular and withVirtualized can be used together but for lists > 100 items prefer one or the other.

`withVirtualized(DrumPicker)` props

In addition to all DrumPicker props (on the wrapped instance):

Prop	Type	Default	Description
`windowSize`	`number`	`20`	Rows rendered above and below the selection
`windowRecenterDebounceMs`	`number`	`100`	Debounce before shifting the slice when scrolling hits the window edge

API reference

`DrumPicker`

Prop	Type	Default	Description
`items`	`T[]`	required	Picker items typed by generic `T` (strings or objects). Display/value mapping follows built-in label resolution and/or `renderItem`.
`selectedIndex`	`number`	`0`	Selected row index
`itemHeight`	`number`	`44`	Row height (dp)
`visibleItemCount`	`number`	`5`	Visible rows (odd recommended)
`textColor`	`string`	`#8E8E93`	Unselected text
`selectedTextColor`	`string`	`#1C1C1E`	Selected text
`textSize`	`number`	`20`	Unselected size (sp)
`selectedTextSize`	`number`	`22`	Selected size (sp)
`backgroundColor`	`string`	`transparent`	Root view background
`containerBackgroundColor`	`string`	`transparent`	`RecyclerView` background
`itemBackgroundColor`	`string`	`transparent`	Row background
`showSelectionIndicator`	`boolean`	`true`	Center lines
`selectionIndicatorColor`	`string`	`#D1D1D6`	Line color
`selectionIndicatorHeight`	`number`	`1`	Line thickness (dp)
`hapticFeedback`	`boolean`	`false`	Light haptic on snap (Android + iOS)
`circular`	`boolean`	`false`	Enable infinite loop scroll. Wraps last->first and first->last.
`enableScrollByTapOnItem`	`boolean`	`false`	Tap a visible row to scroll it to center (Android + iOS)
`onChange`	`function`	—	`nativeEvent: { index, value }`
`onValueChanging`	`function`	—	Fires on each scroll tick while dragging. Use for live sync; debounce heavy UI work.
`renderItem`	`(info) => ReactNode`	—	Custom row renderer. Receives `{ item, label, index, isSelected }`.
`style`	`ViewStyle`	—	Size and layout

`DateDrumPicker`

Prop	Type	Default	Description
`mode`	`DateDrumPickerMode`	`day-month-year`	Which columns to show
`value`	`{ day?, month?, year? }`	—	Controlled value
`onChange`	`function`	—	`{ day, month, year }`
`onValueChanging`	`function`	—	`(column, event) => …` while scrolling; `column` is `day` / `month` / `year`
`minYear`	`number`	now − 100	Year range start (use `minDate` for full date bounds)
`maxYear`	`number`	now + 50	Year range end (use `maxDate` for full date bounds)
`minDate`	`DateConstraint`	—	Minimum selectable date (inclusive). Partial — omit any field.
`maxDate`	`DateConstraint`	—	Maximum selectable date (inclusive). Partial — omit any field.
`monthFormat`	`'short' \| 'long' \| 'number'`	`short`	Month labels
`locale`	`string`	`en`	`Intl` locale for month names
`itemHeight`	`number`	`44`	Passed to each column
`visibleItemCount`	`number`	`5`	Passed to each column
`textColor`	`string`	—	Passed to each column
`selectedTextColor`	`string`	—	Passed to each column
`textSize`	`number`	—	Passed to each column
`selectedTextSize`	`number`	—	Passed to each column
`showSelectionIndicator`	`boolean`	—	Passed to each column
`selectionIndicatorColor`	`string`	—	Passed to each column
`selectionIndicatorHeight`	`number`	—	Passed to each column
`backgroundColor`	`string`	`transparent`	Passed to each column
`itemBackgroundColor`	`string`	`transparent`	Passed to each column
`containerBackgroundColor`	`string`	`transparent`	Passed to each column
`hapticFeedback`	`boolean`	`false`	Passed to each column
`enableScrollByTapOnItem`	`boolean`	`false`	Passed to each column
`style`	`ViewStyle`	—	Row container
`columnStyle`	`ViewStyle`	—	All columns
`columnStyles`	`object`	—	Per column: `day`, `month`, `year`

`DateDrumPicker` modes

Column order is left → right:

`mode`	Columns
`day`	day
`month`	month
`year`	year
`day-month`	day, month
`month-year`	month, year
`day-month-year`	day, month, year
`month-day-year`	month, day, year
`year-month-day`	year, month, day

type DateDrumPickerMode =
  | 'day'
  | 'month'
  | 'year'
  | 'day-month'
  | 'month-year'
  | 'day-month-year'
  | 'month-day-year'
  | 'year-month-day';

Styling

Backgrounds are transparent by default. Only text and optional indicator lines are visible.

<DrumPicker
  items={['Small', 'Medium', 'Large']}
  selectedTextColor="#111827"
  textColor="#9CA3AF"
  selectionIndicatorColor="#D1D1D6"
  backgroundColor="transparent"
  style={{ width: 120, height: 220 }}
/>

Use an odd visibleItemCount (e.g. 5) for a symmetric wheel.

Troubleshooting

Issue	What to try
Must rebuild after install	Native library — run a full Android rebuild
Metro shows old code	`npx react-native start --reset-cache`
Gradle / build errors	`cd android && ./gradlew clean` (Windows: `.\gradlew clean`)
`adb` not found	Install Android SDK Platform-Tools; add to `PATH`
Empty or white picker	Enable New Architecture; upgrade to 0.1.5+ for layout defaults; or set `style={{ width, height: itemHeight * visibleItemCount }}`
Wrong initial row / off-center	Upgrade to 0.1.5+; avoid `key` remount hacks unless needed for other reasons
Props not applied	Rebuild app after native changes; run `yarn build` in the library before packing
iOS build issues	Run `pod install` in `example/ios`; use New Architecture; see CONTRIBUTING.md
Expo Go	Use prebuild + dev build; this library is not in Expo Go
RN 0.81 `uiManagerType` compile error	Upgrade to 0.1.3+
Crash when leaving a screen	Upgrade to 0.1.4+ (safe `onDetachedFromWindow` with react-native-screens)
npm shows “no README”	Often a registry UI lag; run `npm view react-native-drum-picker readme` — if content appears, hard-refresh the package page

Android build fails in Expo / React Native 0.81+

cd android
./gradlew clean

Windows:

cd android
.\gradlew clean

Then rebuild the native app (npx expo run:android or npx react-native run-android).

Crash when leaving a screen

If the app crashes when navigating away from a screen with DrumPicker (especially with react-native-screens transitions), upgrade to 0.1.4+, which avoids unsafe RecyclerView cleanup during onDetachedFromWindow.

New Architecture: This library is a Fabric view. Ensure New Architecture is enabled in your app (required for RN 0.76+).

Development & contributing

git clone https://github.com/scrollDynasty/react-native-drum-picker.git
cd react-native-drum-picker
yarn
yarn build
cd example
yarn android   # or yarn ios

Before a pull request:

yarn lint
yarn build
yarn typecheck
yarn test

Contributing: CONTRIBUTING.md — setup, where to put code and tests, what CI runs on every PR, and review checklist.
Example app: example/README.md.

Name		Name	Last commit message	Last commit date
Latest commit History 131 Commits
.cursor/skills		.cursor/skills
.github		.github
.yarn/releases		.yarn/releases
android		android
codeql-db-js		codeql-db-js
example		example
func-gif		func-gif
img		img
ios		ios
src		src
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.nvmrc		.nvmrc
.release-please-manifest.json		.release-please-manifest.json
.watchmanconfig		.watchmanconfig
.yarnrc.yml		.yarnrc.yml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
DrumPicker.podspec		DrumPicker.podspec
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
babel.config.js		babel.config.js
eslint.config.mjs		eslint.config.mjs
jest.setup.ts		jest.setup.ts
package.json		package.json
react-native.config.js		react-native.config.js
release-please-config.json		release-please-config.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
turbo.json		turbo.json
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

react-native-drum-picker

Preview

Features

Installation

Platform support

Compatibility

Tested with

React Native 0.81+ event dispatch

Basic usage

Layout defaults (0.1.5+)

Examples

Basic picker

Time picker (hour · minute)

Height / weight row (onboarding style)

Controlled selectedIndex

onChange and expensive side effects

Live sync between pickers

Imperative ref API

DateDrumPicker ref — "Today" button

DrumPickerRef API

DateDrumPickerRef API

PickerGroup - synchronize multiple pickers

PickerGroup API

DrumPicker group props

Custom item rendering

renderItem info object

DateDrumPicker

Date range constraints

withVirtualized

Circular scroll

withVirtualized(DrumPicker) props

API reference

DrumPicker

DateDrumPicker

DateDrumPicker modes

Styling

Troubleshooting

Android build fails in Expo / React Native 0.81+

Crash when leaving a screen

Development & contributing

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 9

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Controlled `selectedIndex`

`onChange` and expensive side effects

`withVirtualized(DrumPicker)` props

`DrumPicker`

`DateDrumPicker`

`DateDrumPicker` modes

Packages