react-wheel-picker: an unstyled iOS-style wheel for React

What the component replaces in a React form

react-wheel-picker describes itself as an iOS-like wheel picker for React with smooth inertia scrolling and infinite loop support. The problem it solves is narrow and real: a value selection control that scrolls like the wheel on an iPhone rather than like a dropdown.

The feature list in the README is short and specific. Natural touch scrolling with smooth inertia, mouse drag and scroll for desktop. Infinite loop scrolling. An unstyled core for complete style customization. Full keyboard navigation and type-ahead search.

Each of those addresses a pain point that comes up when you build such a control yourself. Inertia is the part that is genuinely hard to fake, because a scrolling list has to carry velocity after the finger lifts and settle on a detent. Infinite looping, where the wheel wraps from the last value to the first with no visible seam, is the second one. Type-ahead search, where typing a letter jumps to the matching entry, is the third.

The intended audience is React developers building mobile-facing products, or any team that wants iOS-style selection behaviour without shipping a design that copies iOS pixel for pixel. The unstyled core is the key decision, and it shapes everything else about how you adopt the package.

What an unstyled core means for the markup you own

The README calls the core unstyled and says it allows complete style customization. That is a design commitment, and it cuts both ways.

What you gain is control. The component does not decide what your options look like, so you can match an existing design system, follow a brand palette, or match a desktop application that has no business looking like a phone. Because the picker is behaviour rather than appearance, it also fits inside applications that are not mobile at all, which is why mouse drag and scroll for desktop are listed as first-class features rather than afterthoughts.

What you take on is the visual layer. You are responsible for the height of the wheel, the highlight band, the selected item, the fade at the top and bottom, and the alignment of the rows. The README does not enumerate the props or class names involved, so the actual work is not knowable from the README alone: the documentation site is where the API is described, and the README says explicitly to read the getting-started page there for setup and API usage.

The keyboard story deserves a note too. Full keyboard navigation and type-ahead search are claimed features, which puts the component in a usable range for desktop and for anyone who does not use a pointer. The README does not describe how that accessibility is implemented, whether there are ARIA roles or announcements for screen readers, so if that matters to your product you have to check the documentation rather than assume.

The monorepo behind the published package

The repository is not a single package project. It is a pnpm workspace driven by Turborepo, with the picker itself living under packages and the documentation site under apps.

The root manifest describes itself as react-wheel-picker-monorepo, marked private, with [email protected] pinned as the package manager:

{
  "name": "react-wheel-picker-monorepo",
  "version": "0.1.0",
  "private": true,
  "packageManager": "[email protected]",

The scripts show how the pieces relate. There is a dev script that runs Turbo across the workspace, filtered variants for the web app, a build script, and a task dedicated to building the publishable package with the filter @ncdai/react-wheel-picker. A separate publish task changes into packages/react-wheel-picker and runs pnpm publish:release, which is why the repository carries both packages and apps directories rather than the source at the root.

The tree also contains a registry.json, a pnpm-workspace.yaml, turbo.json, tsconfig.json, a .changeset directory, Prettier configuration, and a .vscode directory. The registry.json file is worth a curious reader's attention, since it is the kind of file that usually drives a component or block catalogue rather than a plain package build.

The package metadata is plain MIT, authored by Nguyen Chanh Dai, with the homepage pointing at the documentation domain and funding through GitHub Sponsors.

Changesets and the path from a commit to an npm version

The .changeset directory at the root tells you how releases are cut. Changesets is the tool the project uses to collect version bumps and changelog entries in pull requests, and the root devDependencies include @changesets/cli at a version 2 line. The published package versions follow the pattern 1.2.1, 1.2.2 and 1.2.3, and the three most recent releases in the repository are dated 2026-03-21, 2026-03-22 and 2026-08-23.

That sequencing matters for a consumer. A package released this way carries a version bump decided by the maintainer, not by you, and the changelog for each bump lives with the changeset workflow rather than in the README. If you need to know exactly what changed between two versions, the npm page for @ncdai/react-wheel-picker is the record.

The dependency picture is a monorepo convention worth noting. The root manifest carries resolutions pinning @types/react to 19.2.14 and @types/react-dom to 19.2.3, with TypeScript at a 5.8 line and Turbo at a 2.9 line in development dependencies. That is a signal about the React generation the project is developed against, and it is the first thing to check if you are on an older React and find type conflicts after installing.

For a library user, none of this tooling is required. You install the published package; the monorepo, Turbo and Changesets exist for the maintainers.

Where to get the package and where the real documentation lives

The README does not give an install command, so there is nothing to copy here, and pretending otherwise would be worse than saying so. What it does give is the route: the component is published to npm under the scoped name @ncdai/react-wheel-picker, and the setup and API usage documentation lives at the getting-started page of the project documentation site, which the README links directly.

That split is the most important practical fact about this project. The README is a short overview that states the features, points at the live demo, and sends you to the docs for everything else. The rest of the repository is developer-facing: a contributing guide, a code of conduct, the workspace configuration and the package source.

The live demo at the project homepage is the fastest way to judge the behaviour before installing anything. Since the core is unstyled, the demo is also the place to see what a fully styled example looks like, which is the reference you would start from when building your own visual layer.

If you are evaluating the package rather than consuming it, the repository layout makes the fork cheap: the package source is a single directory under packages, the site is a separate app, and the build is orchestrated by Turbo tasks that are named clearly enough to run in isolation.

Sponsorship, licence and the state of the repository

The project is backed by the Vercel OSS Program, which the README states at the top of the file, and the sponsors table lists further supporters including Mintlify, OpenPanel and a platinum sponsor. There is also a sponsor link back to the author on GitHub.

The licence is MIT, stated both in the README and in the root package manifest, and the LICENSE file sits at the repository root. For a UI component that other people embed in their own applications, MIT is about as permissive as it gets, and it lets you ship commercial products that depend on it.

On activity, the repository is not archived and the last push was on 2026-10-19, with the most recent published package version being 1.2.3 from 2026-08-23. That is a recent release followed by continued work on the branch, which is a healthy pattern for a component library.

Two structural notes for anyone planning to depend on it. First, the component is version 1.x and the API is still moving, so pin the version rather than tracking latest. Second, the maintenance of a small component library depends on one author, so if the picker becomes load-bearing in your product, keep the usage surface narrow enough that you could replace it with your own implementation if you had to.

Where this picker is the wrong tool

There are cases where reaching for a wheel is a mistake, and they are worth naming before adoption rather than after.

If you need a control that behaves like the platform's own picker, this is not it. An iOS-style wheel on Android or Windows will look foreign to those users, and the accessibility story for a rotating wheel in a desktop application is not automatically good even with keyboard navigation and type-ahead. A native select, or a list, is often the more honest control.

If you need the visual result out of the box, the unstyled core works against you. You will be writing the highlight band, the row sizing and the selection affordance yourself, and the documentation is where you learn what hooks are available. Budget for that work.

If your data set is large, be careful. The README describes infinite loop scrolling and type-ahead search, which are natural for the short lists a wheel expects, for example hours, minutes or country codes. The README does not describe virtualisation or list-size limits, so a picker over thousands of entries is untested territory.

The alternative worth comparing against is building the behaviour on a plain scrolling list with CSS scroll snapping, which gives you the visual layer for free and costs you the inertia model, the infinite loop and the type-ahead that this package already solves.

Editorial conclusion

Use react-wheel-picker when you want scrolling-wheel behaviour in a React product and you are willing to own the visual layer, since the core ships unstyled and the README points you at the documentation site for the API. Do not adopt it if you need a fixed visual design out of the box or a native date picker with platform behaviour, and do not treat the README as documentation, because it is a short overview that delegates every setup detail to the hosted docs. Before your first install, read the getting-started page, check the version you are pinning against the published 1.2.3 release from 2026-08-23, and confirm that your React types match the 19.2.x types the monorepo resolves.

Frequently asked questions

Official sources

1. License: MIT
2. ncdai/react-wheel-picker on GitHub
3. Project website
4. README
5. Releases