devaige/WheelPicker: an Android wheel view that bends items along a curve

The problem WheelPicker solves on Android

Android ships Spinner and NumberPicker. Neither renders items on a curve, and neither gives you control over perspective, an atmospheric fade, or a curtain drawn behind the selection band. WheelPicker exists to fill that gap: it is a custom wheel view for Android whose README lists "Data display circulation", "Set visible item count", "Enable atmospheric effect", "Enable perspective effect" and "Curl the items base on mathematic models" among its features. The phrase "strict mathematical modeling" appears in the feature list as the basis for the bend, which is the part most wheel widgets skip.

The audience is narrow and specific. This is an Android UI library written in Kotlin, and the README badges API 21+ and Apache-2.0. If you are building a date selector, a region selector, or a settings control where a native picker feels flat, and your app is already Kotlin with AppCompat or Compose, this is aimed at you. If you are building for iOS, the web, or React Native, the repository has nothing for you despite what the search results around the word "wheel picker" might suggest.

What the wheel actually does: curvature, perspective and curtains

The mechanism visible in the README is a set of independent visual toggles layered on a scrollable list of items. setCurved enables the bend, setAtmospheric enables the depth fade, setPerspective enables the perspective transform, setIndicator and setCurtain draw the selection band and the background panel, and setItemAlignYear and setItemAlignDay control whether items are left-aligned once perspective or curvature is on. Those toggles are not cosmetic switches over a stock ListView; the item positions are computed from a model, which is why alignment has to be configured separately once the items are no longer laid out on a straight line.

The data flow is a plain adapter-style contract. You set a data source, the wheel draws a window of it based on setVisibleItemCount, and selection state is read back either directly when the wheel is stationary or through OnItemSelectedListener when it stops. Version 1.2.1 added a Kotlin functional interface for that listener, so the callback can be written as a lambda. Version 1.2.2 added tapping an adjacent item to jump the selection, and fixed a fling that was interrupted by a touch and left the wheel resting between two items. Version 1.2.0 removed Handler-based animation and upgraded target SDK to 36, which is a meaningful change for anyone who has fought a wheel that keeps animating after the fragment is gone.

One behavior deserves attention before you build on it: the 1.1.1 notes state that all parameters of WheelPicker are reset when you call setData. If you configure text color, item spacing and indicator size once and then swap the data source at runtime, expect to reapply them. That is a design decision, not a bug, and the release notes present it as such.

Installing dev.aige.pub:WheelPicker and rendering a first wheel

The README gives a single Gradle line for the artifact, published under the group dev.aige.pub on Maven Central. Add it to your module build file:

implementation 'dev.aige.pub:WheelPicker:1.2.3'

Since 1.2.2 the internal libraries are marked compileOnly, so the README states you must add the core dependencies yourself or you will hit exceptions. The README shows this block, with the version placeholders left for you to fill in:

implementation("org.jetbrains.kotlin:kotlin-stdlib:<version>")
implementation("androidx.appcompat:appcompat:<version>")
implementation("com.google.code.gson:gson:<version>")

Compose support is optional and listed separately, using the Compose BOM:

implementation(platform("androidx.compose:compose-bom:<version>"))
implementation("androidx.compose.ui:ui")
implementation("androidx.compose.runtime:runtime")

A Maven coordinate is also provided for non-Gradle builds, with groupId dev.aige.pub, artifactId WheelPicker, version 1.2.3 and type pom.

For the first real use, the README does not include a layout snippet or an initialization example. It points to the project WIKI and the Chinese help document for usage, and it lists the widget methods rather than showing them called. The safest first step is therefore to open the WIKI, drop the view into a layout, call setData with your list, and then add setCurved and setPerspective to see the difference between the flat and modeled rendering. The Demo module in the repository is the other place to look: the top-level entries include Demo/src, which is where a working configuration would live.

Where the library gets in your way

The compileOnly change is the largest practical cost. Marking internal libraries compileOnly avoids version conflicts, which is a real benefit, but it moves the burden to you: every consumer now has to declare kotlin-stdlib, appcompat and gson, and the README does not pin versions. If your project has no gson dependency today, adding one for a wheel view is a non-trivial addition to your dependency graph.

Documentation depth is the second limitation. The README's Widgets section is a bulleted method list. setYearFrame, setSelectedYear, setSelectedMonth, setSelectedDay and the rest appear as names with no signatures, no parameter types and no defaults. There is a WheelDatePicker with three linked wheels and a WheelAreaPicker whose data comes from National Bureau of Statistics administrative divisions, but the README does not document the data format either widget expects. The WIKI is where that presumably lives, and the README treats it as the entry point.

There is also no release history beyond the README's own version log, and the last push to the repository was on 2026-03-18. That is roughly six months before the current date, so treat this as a project with no recent commits rather than one under active development. If your policy requires a component with recent activity, this does not meet it. The 1.2.3 fix for an UnsupportedOperationException thrown when the year, month and day pickers are inflated inside WheelDatePicker shows the date widget has had at least one Kotlin dispatch problem in a recent release.

WheelPicker against the platform pickers and against Compose

The obvious alternative is Android's own NumberPicker, which needs no dependency, has no compileOnly obligations, and is maintained as part of the platform. The difference is rendering: NumberPicker draws a flat stack of items with a fading edge. It has no curvature model, no perspective transform, no curtain, and no way to align items along a bent path. If your design calls for the iOS-style curved wheel, NumberPicker cannot produce it and you would be writing the same math WheelPicker already contains.

The second alternative is building the wheel in Jetpack Compose yourself with LazyColumn plus graphicsLayer transforms. That gives you full control and no third-party dependency, at the cost of implementing the item positioning, the fling behavior, the interruption handling and the selection callback. WheelPicker added Compose support in 1.2.0, so the library is usable from a Compose screen, though the README does not show what that integration looks like and the Compose artifacts are listed as optional dependencies rather than required ones.

A third option worth naming is the date picker. If all you need is a date, Material's DatePicker covers it without a wheel. WheelPicker's WheelDatePicker is for the case where the design specifically wants three linked spinning columns, which is a visual requirement Material does not satisfy.

Licence and the cost of upgrading

The project is Apache-2.0, and the README carries the badge to match. That permits commercial use, modification and redistribution provided you keep the licence and notices, and it includes a patent grant. The repository contains a LICENSE file at the top level. This is a description of the licence text, not legal advice; if your organisation has a policy on third-party licences, run it through that process.

Upgrade cost is dominated by the 1.2.2 dependency change. Moving from 1.2.1 or earlier to 1.2.2 or later means auditing your build files for the three core dependencies and adding any that are missing, then confirming your gson version does not conflict with the one WheelPicker expects internally. The 1.2.0 upgrade is the other large step: it moved the group ID from the old coordinate to dev.aige.pub, migrated the code to Kotlin and Material 3, and removed the Handler-based animation. A group ID change means editing the dependency line, not just the version number. For anyone still on the 1.1.x line, the 1.1.1 notes show that setData resets wheel parameters, so a data-swapping screen written against 1.0.x may need its configuration calls moved after each setData.

Editorial conclusion

Adopt dev.aige.pub:WheelPicker if you need a curved, iOS-style wheel in a Kotlin Android app and you are willing to declare kotlin-stdlib, appcompat and gson yourself. Skip it if you need a maintained, frequently released component with a documented API surface, or if you are not on Android at all. Before writing any code, check the Maven Central artifact page for the version you intend to use and open the linked WIKI, because the README lists widget methods without describing their parameters or defaults.

Frequently asked questions

Official sources

1. devaige/WheelPicker on GitHub
2. Issues
3. License: Apache-2.0
4. README