# HeaderAndFooterRecyclerView for AndroidX and legacy RecyclerView migrations

> HeaderAndFooterRecyclerView is a Java Android library and example repository for adding headers, footers, loading states, and related RecyclerView behavior. Its current branch is primarily an AndroidX migration reference, while the original wrapper remains available for existing Support-era integrations.

**cundong/HeaderAndFooterRecyclerView** — A RecyclerView solution, support addHeaderView、addFooterView

- Repository: https://github.com/cundong/HeaderAndFooterRecyclerView
- Stars: 1,391 · Forks: 321
- Language: Java
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/cundong-headerandfooterrecyclerview

## Why HeaderAndFooterRecyclerView exists

HeaderAndFooterRecyclerView addresses a specific Android UI problem: placing a header before a RecyclerView list, placing a footer after it, and coordinating those extra views with ordinary data rows. The repository also preserves examples involving loading states, grid layouts, staggered grids, and scroll callbacks. That original scope explains why it is more than a single view class, although the current project position has changed.

The project is intended for two audiences. Existing applications may depend on the legacy wrapper and need a path away from the Android Support library. New projects are directed toward AndroidX `ConcatAdapter`, which composes separate adapters and handles notification offsets and view-type isolation. The README explicitly says that a new project should use AndroidX `ConcatAdapter`, while an existing integration should review the compatibility notes and legacy usage documentation.

This distinction matters because the repository is not presenting its wrapper as the default modern solution. It calls the wrapper retained for migration and regression coverage. The examples include a legacy path and a modern path, but they do not make every sample a complete production application. The repository is therefore best understood as a compatibility project with executable examples, not as a general purpose RecyclerView feature library.

## The modern ConcatAdapter path

The AndroidX example uses `ConcatAdapter` to combine a header adapter, a data adapter, and a footer adapter. According to the README, this structure corresponds to the required arrangement of header plus data plus footer. `ConcatAdapter` handles adapter composition, notification offsets, and view-type isolation, so the example does not need to implement those details through the old wrapper.

The project also documents a position-related change. Data-row click handling should use `getBindingAdapterPosition()` and check for `NO_POSITION`. This matters because positions passed to an item callback can represent a composed RecyclerView view rather than the position inside the data adapter. The modern sample page reports the item position within the data adapter, which is the meaningful index for data operations such as editing or deletion.

For list changes, the README points to `ListAdapter` and `DiffUtil`. These AndroidX components provide mechanisms for incremental list updates. They are alternatives to older adapter patterns, not features automatically supplied by HeaderAndFooterRecyclerView. The repository does not claim that copying the modern page also provides paging, full-width grid behavior, or every loading state.

## Legacy wrapper scope and limitations

The `library` module contains the legacy wrapper, position and span helpers, and scroll callbacks. The `sample` module provides a minimal legacy header/footer example. The `samplePlus` module combines an AndroidX grid example with legacy linear, grid, and staggered-grid paging demonstrations. This layout preserves original behavior while making the current AndroidX direction visible.

The legacy integration is constrained by the migration history. The branch changes `android.support` types to AndroidX and raises the minimum SDK from 14 to 21 for `library` and `sample`. Applications still using the old Support library must update imports and rebuild. The repository does not publish or replace Maven artifacts, so the project cannot be treated as a packaged drop-in release for an existing dependency setup.

The wrapper is also not the right tool for every header or footer problem. `ConcatAdapter` does not choose grid or staggered-grid spans, so a full-width header or footer still needs explicit layout parameters and span handling. Managed pagination is another boundary. Moving to Paging requires changing data requests and pagination state, not merely replacing a scroll listener. The README does not document a complete rollback procedure for an integration, and it does not claim support for every historical RecyclerView edge case.

## Building the repository on JDK 17 or 21

The repository documents JDK 17 or 21, Android SDK 36, Build Tools 35.0.0, and Android API 21 or later. Set `ANDROID_HOME`, or configure an untracked `local.properties` as described in `CONTRIBUTING.md`. The documented setup command installs the required SDK packages. A first build downloads dependencies, so the command may require network access and more time than later builds.

The following command runs host-side unit tests, assembles a debug APK, and runs lint. The README says that the tests run on the host without an emulator. The build pins Gradle 8.13, AGP 8.11.1, RecyclerView 1.4.0, and AppCompat 1.7.1, so dependency and toolchain consistency are part of the documented setup rather than incidental details.

```sh
sdkmanager "platforms;android-36" "build-tools;35.0.0" "platform-tools"
./gradlew testDebugUnitTest assembleDebug lintDebug --console=plain
```

On Windows, the README specifies `gradlew.bat` instead of the Unix wrapper. Open the root project in Android Studio and run `samplePlus` to inspect the AndroidX `ConcatAdapter (AndroidX)` page. The two demo apps have different application IDs and can be installed together.

## Grid headers, footers, and paging boundaries

The repository gives a concrete example of a composition problem that remains after adapter migration. In `samplePlus`, the AndroidX page uses a grid, and its header and footer span both columns. This illustrates why `ConcatAdapter` alone is insufficient for span selection. The adapter can compose the views, but the layout code still has to assign the appropriate full-span layout parameters.

The README lists explicit span lookup and full-span layout parameters as the AndroidX approach for full-width grid and staggered-grid decorations. That is a separate responsibility from header/footer composition. A developer copying only the modern page may therefore reproduce a linear list successfully but miss the span configuration required for a grid.

The same boundary applies to pagination. The repository suggests Paging, `PagingDataAdapter`, and `LoadStateAdapter` for managed pagination and retry UI. It also states that this migration requires moving data requests and pagination state. The legacy `samplePlus` paging demos should not be read as evidence that the repository provides a new managed paging abstraction. The README explicitly says that a complete Paging app is not included.

For device checks, `CONTRIBUTING.md` contains a smoke-test checklist. That is the appropriate place to inspect documented device behavior, especially for interactions that host unit tests cannot reproduce. The repository does not claim that CI covers every historical edge case.

## Maintenance, licensing, and upgrade cost

The repository is not archived, and its last push was on 2026-09-06. Its stated maintenance scope is narrower than the original feature set: reproducible builds, confirmed defects, necessary compatibility fixes, and documentation or examples. New general-purpose adapter features are outside that scope. This means an upgrade may focus on build correctness and migration support rather than expanding the wrapper API.

The project uses the Apache-2.0 license. The repository includes the license file at the root. The documentation does not provide legal advice or a separate warranty analysis, so adoption decisions should account for the actual obligations of that license rather than treating the license identifier as a guarantee of compatibility.

The main upgrade cost is migration work. Support-era consumers must move from `android.support` imports to AndroidX and rebuild against a minimum API of 21. New consumers should avoid introducing the legacy wrapper at all and start from the `samplePlus` AndroidX page. The repository has no GitHub releases and does not publish or replace Maven artifacts, so version discovery and artifact integration are not handled as a conventional release process.

## Conclusion

Adopt the AndroidX sample when building a new header-and-footer list, and use the legacy library only when maintaining a Support-era integration that has not yet migrated. Do not treat this branch as a drop-in update or as a complete paging solution. Verify the Android SDK, minimum API level, adapter migration path, notification behavior, and the required build commands before integrating it.

## FAQ

### What should I use for headers and footers in a new AndroidX RecyclerView?

The README directs new projects to use AndroidX `ConcatAdapter`, with separate header, data, and footer adapters. The `samplePlus` module contains the AndroidX example, and its modern page does not use an API from the legacy library.

### Can HeaderAndFooterRecyclerView replace my old Android Support integration without changes?

No. The README says this branch is not a drop-in update for old Android Support library consumers. Those applications must update `android.support` imports to AndroidX and rebuild, with the documented minimum SDK raised to API 21 for `library` and `sample`.

### Does HeaderAndFooterRecyclerView handle AndroidX Paging automatically?

No. The README points to Paging, `PagingDataAdapter`, and `LoadStateAdapter` for managed pagination, but says migration requires moving data requests and pagination state. The repository does not include a complete Paging app.

## Sources

- [cundong/HeaderAndFooterRecyclerView on GitHub](https://github.com/cundong/HeaderAndFooterRecyclerView)
- [Issues](https://github.com/cundong/HeaderAndFooterRecyclerView/issues)
- [License: Apache-2.0](https://github.com/cundong/HeaderAndFooterRecyclerView/blob/master/LICENSE)
- [README](https://github.com/cundong/HeaderAndFooterRecyclerView/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cundong-headerandfooterrecyclerview