# z-paging for uni-app: Pull-to-refresh and virtual list paging

> z-paging is a JavaScript component for uni-app that manages pull-to-refresh, load-more behavior, result arrays, empty states, and virtualized lists across Vue, nvue, Vue 2, Vue 3, app, H5, HarmonyOS Next, and mini-program environments. Its main value is reducing repeated pagination code, while its platform-specific rendering paths and broad configuration surface require careful integration checks.

**SmileZXLee/uni-z-paging** — 【uni-app下拉刷新、上拉加载】高性能，全平台兼容(ios、安卓、鸿蒙next、h5以及各家小程序)。支持vue、nvue、vue2、vue3，使用wxs+renderjs实现。支持虚拟列表，支持自定义下拉刷新、上拉加载更多，支持自动管理空数据图、点击返回顶部，支持聊天分页、本地分页，支持国际化等数百项配置，流畅渲染百万级列表数据。

- Repository: https://github.com/SmileZXLee/uni-z-paging
- Website: https://z-paging.zxlee.cn
- Stars: 1,479 · Forks: 101
- Language: JavaScript
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/smilezxlee-uni-z-paging

## Why uni-z-paging exists in a uni-app list

z-paging addresses a recurring problem in uni-app applications: developers must coordinate a network request, a page or cursor, loading states, refresh behavior, and the result list without duplicating that logic in every screen. The repository describes a two-step setup in which a developer binds a network request method and binds the pagination result array. The component then manages the common pull-to-refresh and pull-up-load-more behavior.

The intended users are uni-app developers working with Vue, nvue, JavaScript, or TypeScript across app, H5, HarmonyOS Next, and mini-program targets. The documented compatibility matrix includes Vue 2 and Vue 3, and the repository contains both an Options API demo and a Vue 3 Composition API demo. This makes it more relevant to applications that publish or maintain several platform variants than to a standalone JavaScript package that only runs in a browser.

The component is not limited to remote pagination. Its documented features include local paging, chat pagination, automatic empty-data handling, a return-to-top action, last-updated-time display, sticky effects, internal scroll containers, and page scrolling. That breadth is useful for product teams, but it also means that adopting z-paging introduces a component with more modes than a basic list requires. The right evaluation point is therefore the application's actual list behavior, not the size of the feature catalog.

## The data path from request method to rendered list

The repository describes z-paging as a component that owns pagination state instead of requiring each page to define pagination-related variables in its data object. A screen supplies the request method and the result array. The component coordinates the request lifecycle and feeds the returned records into the bound list, while also handling the interaction states associated with refreshing and reaching the end of a page.

For larger lists, the documented virtual-list mode uses wxs and renderjs in the supported environments. The README specifically identifies app-vue, H5, WeChat mini-program, and QQ mini-program as using wxs plus renderjs to implement pull-to-refresh at the view layer. That detail matters because the implementation is not described as one identical JavaScript routine everywhere. The rendering path differs by target, which makes platform-specific behavior part of the component's design rather than an incidental packaging detail.

The component also supports both its built-in automatic pagination and event-driven handling for refresh and reaching the bottom. In other words, developers can let z-paging manage the usual flow or intercept those events and apply custom logic. This is a meaningful choice for screens such as chat interfaces, where insertion direction and scroll position differ from an ordinary feed. The README does not document the internal request contract, request cancellation rules, retry policy, or exact event ordering, so those details must be checked against the project documentation before they are relied upon.

## Repository layout and the first integration choices

The repository separates runnable examples from the reusable component. The `demo/z-paging-demo` directory uses the Options API and supports Vue 2 and Vue 3. The `demo/z-paging-vue3-demo` directory uses the Composition API and supports Vue 3. The `z-paging` directory contains the component source. The README says that this directory can be copied directly into a project's `uni_modules` folder, or that its subcomponents can be copied into a `components` directory.

For a first integration, the repository provides a concrete learning path: open the demo that matches the project's Vue style, compare the request binding and list binding, then copy the `z-paging` directory into the application. The repository does not provide an npm installation command, CLI setup step, or configuration file in the README. It also does not document a required initialization call for the Vue options API or Composition API. Those instructions should therefore come from the linked project documentation rather than being inferred from the folder names.

The demo directory is also the appropriate place to verify project-specific constraints. One demo supports Vue 2 and Vue 3, while the other is limited to Vue 3. A team using nvue, HarmonyOS Next, or a mini-program should not assume that the existence of a demo proves identical behavior on every target. The repository's online demo and documentation provide additional places to inspect, but the README does not state that those resources replace testing in the consuming application.

## What virtual lists and chat paging change

Virtual-list support is the feature most likely to change an application's rendering design. The README claims that z-paging can render million-level list data through virtual-list support, and its preview labels a virtual-list demonstration as rendering more than 10,000 items. These are repository claims and documented demonstrations, not independently measured results. The practical question is whether the target platform, item height assumptions, fixed or dynamic layout, and surrounding scroll container are compatible with the component's rendering path.

A virtual list can reduce the number of item views held by the view layer, but it does not remove the need for a usable data source or a clear item structure. If records have variable heights, or if an item depends on platform-specific components, the integration may need attention beyond ordinary array binding. The README does not specify the precise virtual-list configuration keys, supported item-height modes, or behavior when measurements change after loading. Those are limitations of the documented README, not claims that the feature is unsuitable.

Chat pagination is a separate mode with different interaction requirements. It is intended for message histories where new content can appear at the opposite end from older records. The repository lists chat pagination among its supported modes but does not explain its request parameters, anchor behavior, duplicate handling, or scroll restoration rules in the README. A chat screen should therefore be evaluated against those missing details rather than treated as an ordinary feed with a different label.

## Platform coverage versus implementation boundaries

The stated platform coverage is broad: app, H5, HarmonyOS Next, and multiple mini-program environments are listed, with Vue, nvue, Vue 2, Vue 3, JavaScript, and TypeScript supported according to the README. That range is a reason to consider z-paging for a cross-platform uni-app codebase. It is not the same as saying that every feature uses the same code path on every platform. The documented wxs and renderjs implementation already indicates platform-specific rendering work.

The component is designed for low coupling, meaning a page can delegate standard pagination behavior instead of maintaining all related state. It also permits a full-screen layout or placement inside an arbitrary container. That flexibility can reduce code duplication, although it moves responsibility to the consuming page when custom layouts or custom refresh and load-more effects are selected. The README does not define a compatibility matrix for each feature and platform combination.

For teams maintaining app and mini-program releases, this is the principal adoption risk. They should identify the exact platforms in the release pipeline and compare those targets with the component's documented demos. They should also inspect whether their pages use page scrolling, an internal `scroll-view`, nvue, or a modal container, since the repository lists those as supported scenarios but does not provide detailed configuration instructions in the README.

## Maintenance, releases, and the MIT source boundary

The repository is not archived. Its last push was on 2026-07-10, so it has recent repository activity within the stated release context. The listed releases include `2.8.8` on 2025-09-16, `2.8.7` on 2025-05-29, and `2.8.6` on 2025-03-16. These release entries indicate versioned distribution, but they do not by themselves establish that every supported platform receives fixes at the same time.

The project is licensed under MIT. That means the repository grants the permissions and conditions associated with the MIT License, subject to the license text and applicable obligations. This article does not provide legal advice or interpret how a particular application should handle distribution, notices, or third-party dependencies. The repository includes a `LICENSE` file, which is the source to consult for the exact terms.

The README also warns users to check the version differences before updating the component and links to an upgrade guide. That warning is significant for this project because it supports several Vue and uni-app environments and offers multiple configuration modes. The upgrade cost is not only the file copy itself. Developers need to compare component changes with their app's Vue version, target platforms, page structure, and custom pagination behavior. The README does not document a migration command or an automated upgrade tool.

## Conclusion

Adopt z-paging when a uni-app application needs a shared pagination component across several rendering targets and the team can validate its wxs and renderjs behavior on each required platform. Do not adopt it solely because the README describes million-item rendering, or when a small application needs only a fixed request-and-list flow. Before adoption, verify the component's compatibility with the application's Vue version, target platforms, container layout, data source, and required pagination mode; the repository itself points maintainers to the version differences page before upgrading.

## FAQ

### How do I install z-paging in a uni-app project?

The README does not document an npm or command-line installation step. It says to copy the `z-paging` directory into the project's `uni_modules` folder, or copy its subcomponents into a `components` directory, and it links to the project documentation for further setup.

### Which Vue API does the z-paging demo support?

The `demo/z-paging-demo` example uses the Options API and supports Vue 2 and Vue 3. The separate `demo/z-paging-vue3-demo` example uses the Composition API and is documented as supporting Vue 3 only.

### Does z-paging support local data and chat pagination?

Yes. The README lists local pagination and chat pagination among the component's supported features. It also lists virtual lists, custom refresh and load-more effects, automatic empty-data management, and a return-to-top control.

## Sources

- [License: MIT](https://github.com/SmileZXLee/uni-z-paging/blob/main/LICENSE)
- [Project website](https://z-paging.zxlee.cn)
- [README](https://github.com/SmileZXLee/uni-z-paging/blob/main/README.md)
- [Releases](https://github.com/SmileZXLee/uni-z-paging/releases)
- [SmileZXLee/uni-z-paging on GitHub](https://github.com/SmileZXLee/uni-z-paging)

---

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