AndroidPicker: a Java picker library for dialogs Android never shipped

What AndroidPicker actually replaces

Android's platform widgets cover dates and times, and Material components cover a few more cases. They do not cover a wheel of goods categories, a three-level province/city/county address chain, a licence-plate picker, a colour picker or a file browser. AndroidPicker collects those into one library, and the README lists the intended uses directly: birth dates and business hours for the date and time pickers, gender, ethnicity, occupation and education for the single-option picker, plate numbers and fund investment dates for the two and three level linkage picker, age, height, weight and temperature for the number picker, hotel and flight booking dates for the calendar picker, plus colour, file, directory and image selection.

The audience is Android developers working in Java, which is the repository's primary language. The minimum is API 19, stated in the README badge, so the library targets a wider device range than many modern Android libraries. If your app already uses Material dialogs and you only need a date, the platform picker is less code and fewer dependencies. AndroidPicker earns its place when you need the wheel interaction or the linked data sets that the platform does not provide.

Module layout and the 3.x rewrite

The library is split by concern rather than shipped as one artefact. The repository contains Common, WheelView, WheelPicker, AddressPicker, CalendarPicker, ColorPicker, FilePicker and ImagePicker directories, each published as a separate JitPack coordinate. Common holds the base dialog window used for custom popups. WheelView holds the wheel control itself, for building your own wheel picker. WheelPicker carries the single-option, number, two and three level linkage, date and time pickers. The rest map to their names.

That split is the main architectural decision, and it is a sensible one: an app that only needs a colour picker does not pull in the address data. The README warns that version 3.0.0 rebuilt the underlying code, improved performance and made XML layout friendlier, and that 3.x APIs differ from 1.x and 2.x, so upgrades need care. The 1.x-support and 2.0-androidx branches are frozen for anyone who cannot move. The README also notes that the library needs no extra ProGuard configuration, which removes one common integration chore.

Data-driven pickers read from assets. The README states that you can override assets/china_address.json to customise province, city and district data, and that AddressPicker can be pointed at a different JSON file with a parser builder that names the code, name and child fields for each level. The same override pattern applies to visual behaviour: the README mentions replacing DialogSheetAnimation to change the popup animation.

Installing AndroidPicker from JitPack and showing a first picker

AndroidPicker is not on Maven Central. The README directs you to JitPack, and the repository includes a .jitpack.yml file, which is the build configuration JitPack reads. If your project uses Gradle below 7.0, add the repository in the root build.gradle; from 7.0 onward, add it in settings.gradle instead. The README gives both forms.

dependencyResolutionManagement {
    repositories {
        // JitPack 远程仓库：https://jitpack.io
        maven { url 'https://jitpack.io' }
    }
}

Then add only the modules you need in the module-level build.gradle. The README says the dependencies do not all have to be included. Replace <version> with the release you want to pin, such as 4.1.15.

dependencies {
    implementation 'com.github.gzu-liyujiang.AndroidPicker:Common:<version>'
    implementation 'com.github.gzu-liyujiang.AndroidPicker:WheelPicker:<version>'
    implementation 'com.github.gzu-liyujiang.AndroidPicker:AddressPicker:<version>'
}

A first real use is the option picker. The README example builds a list of beans, sets a title, a body width, the data, a default position and a listener, then calls show(). The commented lines in the same example show how to reach the wheel layout to change indicator, text colour, text size, bold selected text and the curtain highlight.

List<GoodsCategoryBean> data = new ArrayList<>();
data.add(new GoodsCategoryBean(1, "食品生鲜"));
data.add(new GoodsCategoryBean(2, "家用电器"));
OptionPicker picker = new OptionPicker(this);
picker.setTitle("货物分类");
picker.setBodyWidth(140);
picker.setData(data);
picker.setDefaultPosition(2);
picker.setOnOptionPickedListener(this);
picker.show();

For a date, the README shows DatePicker with an optional DateWheelLayout where you set the date mode, the unit labels, a formatter, and a range built from DateEntity.target and DateEntity.today. AddressPicker takes an AddressMode such as PROVINCE_CITY, an optional default value, and an OnAddressPickedListener. The README points to API.md for the full surface, and to the demo module and demo.apk for runnable behaviour.

Where AndroidPicker gets in your way

The clearest limitation is stated by the maintainer, not by a critic. The README carries a note that from 2022 the author stopped doing Android development, that the project has become stable, and that contributors are needed because the author can no longer contribute code. The last push was on 2026-03-21, which is recent, but the release history is uneven: 4.1.13 in December 2023, 4.1.14 in November 2024, then 4.1.15 in March 2026. Anyone whose release policy requires a dependency with a predictable cadence should weigh that.

Distribution is the second constraint. Artefacts come from JitPack, a build-on-demand service, not a central repository. If JitPack cannot build a tag, the coordinate does not resolve, and the README's own note that the API document exists separately from the code means you should read API.md against the version you pin rather than assume the README examples are current.

The bundled address data is a third. AddressPicker reads assets/china_address.json, which is Chinese province, city and district data. The README documents overriding that file and supplying a custom parser, so other countries are possible, but you are writing the parser configuration and sourcing the data yourself. If your app needs a country outside that structure, the address picker is not the tool; a plain option picker over your own list is.

Finally, the wheel look is a choice, not a neutral default. Wheel pickers read well for ordered values and poorly for long unordered lists, where a searchable list or a scrollable dialog is faster to use. The library will render a thousand options in a wheel; that does not make it a good idea.

AndroidPicker versus MaterialDatePicker and the platform pickers

The honest comparison is with what Android already ships. MaterialDatePicker and the platform DatePickerDialog and TimePickerDialog cover date and time selection, they are maintained with the platform, and they add no third-party dependency or JitPack repository. If your requirement is a calendar date range, MaterialDatePicker handles it, and the related searches around MaterialDatePicker and time picker dialogs reflect how often that is the default answer.

The difference in approach is the interaction model and the data. Material pickers present a calendar grid or a clock face. AndroidPicker presents wheels, and the README's own examples show why that matters for its use cases: a birth date on a wheel is a few flicks, a goods category is a single column, a province/city/county address is three linked columns that reset or hold per the setResetWhenLinkage setting. Material has no equivalent for the linkage, address, plate, colour or file pickers at all. For the image case, the modern platform answer is the Android photo picker, which the related searches also show people looking for; AndroidPicker's ImagePicker is a separate module with its own README, and the two are not interchangeable in permissions or behaviour.

So the split is not quality, it is scope. Use platform and Material components where they cover the case. Reach for AndroidPicker when the wheel interaction or the linked data sets are the requirement, and accept JitPack plus a maintainer who has publicly stepped back.

Editorial conclusion

AndroidPicker fits teams maintaining a Java or Kotlin Android app that needs wheel-style date, time, option, address or calendar selection and is comfortable pulling artefacts from JitPack. It does not fit projects that require an actively developed dependency with a responsive maintainer, since the README states the author stopped Android development in 2022 and the last push was on 2026-03-21. Before adopting, verify that the module you need resolves at the version you pin, check the API document against the 3.x API described in the README, and confirm that the bundled china_address.json data matches the regions you must support, because that data is what the AddressPicker ships with.

Frequently asked questions

Official sources

1. gzu-liyujiang/AndroidPicker on GitHub
2. Issues
3. README
4. Releases