BannerViewPager: A ViewPager2 Banner Carousel for Android

What BannerViewPager solves for Android screens

A looping banner on Android is usually assembled from a ViewPager2, a custom adapter, a handler for auto-scroll, a page transformer for the peeking-card look, and a separate indicator view that has to stay in sync. BannerViewPager packages that assembly into one component. The README states its purpose directly: "一行代码实现循环轮播" (one line of code for a looping carousel), with "一屏三页任意变" (three pages on one screen, freely adjustable) and "指示器样式任你挑" (indicator styles for you to choose).

The intended audience is an Android app developer who needs a promotional or content carousel and does not want to maintain the pager plumbing. The README's positioning claim lists Tencent Video, QQ Music, KuGou, AliPay, Tmall, TaoBao, YouKu, Himalaya, NetEase Music and Bilibili as apps whose banners could be implemented with it. That is a statement of fit, not a list of adopters, and the repository does not provide evidence of production use in those apps.

The project is Java, targets API 19 and above according to its README badge, and is licensed Apache-2.0. The last push to the default branch was on 2026-03-19, and the most recent release listed is 3.5.17 from 2025-08-23. The repository is not archived.

How the ViewPager2 loop and the indicator split work

The mechanism is a wrapper over ViewPager2 rather than a from-scratch pager. The README says the library is "Based on ViewPager2", and the repository layout reflects that: the library module is bannerview/, with a separate app/ module that holds the demo. The looping behaviour, the page style and the indicator are all configured through the component rather than through a hand-written adapter.

Page appearance is controlled by setPageStyle() and setRevealWidth(). The README names three styles in its preview table: MULTI_PAGE, MULTI_PAGE_SCALE and MULTI_PAGE_OVERLAP, and says more styles can be produced by combining setPageStyle() with setRevealWidth(). That is the part that gives the peeking-card and scaled-neighbour looks without a custom PageTransformer.

The indicator is no longer inside this library. The README states that the indicator library "was split from BannerViewPager" into a separate repository, ViewPagerIndicator, and links to it for details. The split is the most consequential architectural fact for anyone evaluating this project: if you want the built-in indicators, you are pulling in a second artifact with its own release cadence. The README lists three indicator styles (CIRCLE, DASH, ROUND_RECT) and five slide modes (NORMAL, SMOOTH, WORM, COLOR, SCALE), configured through setIndicatorStyle and setIndicatorSlideMode. For anything else, the README says you extend BaseIndicatorView or implement the IIndicator interface and override its methods.

Installing BannerViewPager and a first banner

The README does not print Gradle coordinates. It links to a wiki page titled "1.Quick Starts", and the JitPack badge in the README points at the distribution channel. The README also links to wiki pages for the API, multiple view types, ViewBinding and DataBinding, and custom IndicatorView. So the install path runs through the Quick Starts wiki page, and the JitPack page for the project is where the version string comes from. The README does not contain a dependency snippet to copy, so check those two pages before writing your build file.

The README does give one concrete pointer for sample code: the page-style sample lives at app/src/main/java/com/example/zhpan/banner/fragment/PageFragment.kt, and the indicator sample at app/src/main/java/com/example/zhpan/banner/fragment/IndicatorFragment.java. The demo APK linked from the Preview section is the reference for what each style is supposed to look like.

Two setters drive the page styles the README tabulates. setPageStyle() selects the style, and setRevealWidth() sets how much of the neighbouring pages is exposed. The README says the additional styles shown in its tables are produced by using the two together. It does not print the call sites, so read them from PageFragment.kt before copying anything into your own code.

After wiring the component up, what you should see is a pager that shows the current page with the next and previous pages partially visible when a MULTI_PAGE-family style is set, and that loops when it reaches the end. The README's demo APK is the only behaviour reference it provides.

Where BannerViewPager is the wrong tool

The dependency on ViewPager2 is the hard boundary. If your app is still on the original ViewPager, or you have deliberately moved to a different paging primitive, this library does not meet you there; the README describes it as based on ViewPager2 and does not document a ViewPager fallback. That also means ViewPager2's own adapter requirements and page-change behaviour are inherited rather than replaced.

The indicator split is the second constraint. Because the indicator lives in the separate ViewPagerIndicator repository, the README is silent on which indicator versions pair with which BannerViewPager versions. You are managing two artifacts and their compatibility yourself. The README also does not document what happens when the indicator and the pager disagree, for example if the page count changes after the indicator is attached.

There is no documented rollback or migration guidance. The README lists wiki pages for Quick Starts, API, multiple view types, ViewBinding and DataBinding, and custom indicators, but nothing about upgrading between major versions or handling breaking changes. The release list shows frequent patch releases (3.5.15, 3.5.16, 3.5.17 within a few weeks of each other in 2025), which suggests the patch line moves quickly but tells you nothing about API stability across the 3.x series. If you pin a version and later need to move, the README does not tell you what to check.

BannerViewPager against ViewPager2 plus a standalone indicator

The realistic alternative is what BannerViewPager is built on: use ViewPager2 directly and add an indicator library separately, or write the indicator yourself. The difference is where the looping logic lives. With plain ViewPager2 you implement the wrap-around yourself, typically by inflating the adapter's item count and mapping positions back to real items, and you write the PageTransformer that produces the scaled or overlapping neighbour pages. BannerViewPager moves that into setPageStyle() and setRevealWidth(), at the cost of accepting its page-style vocabulary instead of an arbitrary transformer.

A second alternative is a non-ViewPager2 carousel, such as a RecyclerView with a snapping layout manager. That approach gives you full control over the item layout and the scroll physics, and it does not inherit ViewPager2's adapter contract. It also means you build the loop, the auto-scroll and the indicator from scratch, which is the work BannerViewPager exists to remove.

The comparison that matters is not feature count. It is whether you want a banner component with a fixed set of page styles and indicator styles, or a pager you shape yourself. BannerViewPager is the former. The custom-indicator escape hatch (extend BaseIndicatorView or implement IIndicator) softens the second half of that trade-off, but the page styles are still the ones the library defines.

Maintenance, releases and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-03-19, which is within six months of the current date, so the project is still receiving commits. The release list shows 3.5.17 on 2025-08-23, 3.5.16 on 2025-08-09 and 3.5.15 on 2025-08-04. That is a tight patch cadence in August 2025, followed by commits into March 2026 without a newer listed release. The README does not explain the release policy or how long a version line is supported.

Upgrade cost is hard to estimate from the repository alone. There is no changelog file in the top-level entries, and the README does not link to release notes. The wiki pages cover usage, not migration. The practical implication is that you should read the wiki page for the API surface you depend on before moving versions, and pin the version in your build file rather than tracking a dynamic version.

The licence is Apache-2.0. The LICENSE file is at the repository root, and the README carries the standard header text, "Licensed under the Apache License, Version 2.0". Apache-2.0 permits commercial and closed-source use and includes a patent grant. It also requires that you retain the licence and notice files and state significant changes. This is a description of the licence text, not legal advice; if your organisation has a policy on bundled dependencies, route the LICENSE file through it.

Editorial conclusion

Adopt BannerViewPager if you are on Android with API 19 or higher, already use ViewPager2, and want looping plus indicator styles without writing a pager adapter yourself. Do not adopt it if you need a non-ViewPager2 carousel, or if you cannot add JitPack as a repository. Before committing, read the Quick Starts wiki page for the version you install, confirm which ViewPagerIndicator artifact pairs with it, and read the Apache-2.0 LICENSE file in the repository.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. zhpanvip/BannerViewPager on GitHub