# @cycjimmy/h5-pages

> full h5 page plugin based on swiper

Latest version **5.0.0** (published 2026-11-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install @cycjimmy/h5-pages
pnpm add @cycjimmy/h5-pages
yarn add @cycjimmy/h5-pages
bun add @cycjimmy/h5-pages
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.0.0 |
| Published | 2026-11-18 |
| First published | 2020-03-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^22.22.2 \|\| ^24.15.0 \|\| >=26.0.0 |
| Dependencies | 0 |
| Unpacked size | 47.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 4 |
| Author | cycjimmy |
| Maintainers | cycdpo |
| Keywords | full, h5, page, swiper |

## Links

- npm: https://www.npmjs.com/package/@cycjimmy/h5-pages
- Repository: https://github.com/cycjimmy/h5-pages
- Homepage: https://github.com/cycjimmy/h5-pages#readme
- Issues: https://github.com/cycjimmy/h5-pages/issues
- npm.io page: https://npm.io/package/@cycjimmy/h5-pages

## Alternatives

- [adhdev](https://npm.io/package/adhdev.md) — 11.1K weekly downloads
- [react-slide-button](https://npm.io/package/react-slide-button.md) — 310 weekly downloads
- [better](https://npm.io/package/better.md) — 42 weekly downloads
- [react-native-swipe-image](https://npm.io/package/react-native-swipe-image.md) — 22 weekly downloads
- [nl.fokkezb.pulltorefresh](https://npm.io/package/nl.fokkezb.pulltorefresh.md) — 11 weekly downloads

## Recent versions

- 5.0.0 (latest) — 2026-11-18
- 4.3.3 — 2024-10-25
- 4.3.2 — 2024-07-17
- 4.3.1 — 2023-02-23
- 4.3.0 — 2022-11-24
- 4.2.0 — 2022-08-26
- 4.1.3 — 2022-06-21
- 4.1.2 — 2022-03-26
- 4.1.1 — 2022-03-25
- 4.1.0 — 2022-03-25
- 4.0.0 — 2022-03-18
- 3.2.0 — 2022-03-16
- 3.1.3 — 2022-03-16
- 3.1.2 — 2022-03-16
- 3.1.1 — 2020-11-12
- … 11 more at https://npm.io/package/@cycjimmy/h5-pages/versions

## README

# H5 Pages
[![Test CI][workflows-badge-image]][workflows-url]
[![libraries dependency status][libraries-status-image]][libraries-status-url]
[![libraries sourcerank][libraries-sourcerank-image]][libraries-sourcerank-url]
[![Coverage Status][coverage-image]][coverage-url]
[![Release date][release-date-image]][release-url]
[![vite][vite-image]][vite-url]
[![semantic-release][semantic-image]][semantic-url]
[![vitest][vitest-image]][vitest-url]
[![npm license][license-image]][download-url]

* H5 pages based on swiper5+. ([Demo][github-pages-url])

Language: [En][Readme-url-En] | [中文][Readme-url-ZhCN]
***

## Install
[![NPM version][npm-image]][npm-url]
[![NPM bundle size][npm-bundle-size-image]][npm-url]
[![npm download][download-image]][download-url]

```shell
# via npm
$ npm install @cycjimmy/h5-pages --save

# or via yarn
$ yarn add @cycjimmy/h5-pages
```

## Module format

The package is **ESM only**:

| File | Format | Purpose |
| --- | --- | --- |
| `dist/h5-pages.esm.js` | ESM | `main`, `module` and `exports` entry (bundlers, `import`) |
| `dist/h5-pages.umd.js` | UMD | unminified browser build for `<script>` tags |
| `dist/h5-pages.umd.min.js` | UMD | minified browser/CDN build, `browser`/`unpkg`/`jsdelivr` |
| `dist/index.d.ts` | Types | TypeScript declarations for `types` and the `exports` `types` condition |

* There is no CommonJS bundle. Node.js 20.19+ / 22.12+ can `require()` the ESM
  entry, because those versions load an ES module synchronously.
* The UMD builds target ES2015, so Internet Explorer is no longer supported.
* The stylesheet is not shipped as a separate `.css` file: the CSS Modules output
  is inlined into the entry chunk and injected as a `<style>` element while the
  module is evaluated, so a plain `<script>` tag needs nothing else.
* Type declarations ship with the package, so no `@types/*` package is needed.
  They describe Swiper structurally and never reference `swiper` itself.

The toolchain needs Node.js `^22.22.2 || ^24.15.0 || >=26.0.0` (see `engines` in
`package.json` and the requirements in [CONTRIBUTING.md](CONTRIBUTING.md)).

## Usage
**h5-pages based on [Swiper5+](https://github.com/nolimits4web/Swiper). Add script of swiper in your project first.**

### Methods

#### `init()`: Initialization function

```javascript
import { init } from '@cycjimmy/h5-pages'
import Swiper from 'swiper'

init({
  Swiper, // constructor of Swiper
  pages: [page1, page2], // An array of Page instances
  containerExtraHtml: `<div class="swiper-pagination"></div>`, // Extra Html under swiper-container, such as navigator, etc.
  swiperOptions: { // swiper configuration(loop is not supported)
    direction: 'vertical',
    pagination: {
      el: '.swiper-pagination',
    },
  },
  compatibleWithSafeArea: true, // Whether it is compatible with the safe area of screen. The default is true.
})
```

#### `getPageByName(name)`: Get a single page by name

#### `changePageTo(name, speed)`: Jump to the page with the specified name

* `name`: Page name.
* `speed`: Transition duration (in ms).

### Use `h5Pages` to Get the Core Properties

* `h5Pages.root`: H5 root element. Don't put pages like popups directly in `body`, it is recommended to use `root` as parent.
* `h5Pages.swiper`: Main swiper instance for H5.

```javascript
import { h5Pages } from '@cycjimmy/h5-pages'

console.log(h5Pages.root) // H5 root element
console.log(h5Pages.swiper) // swiper instance
```

### Single Page

#### Build Single Page

##### Build directly with the default Page

```javascript
import { Page } from '@cycjimmy/h5-pages'

const page = new Page({
  name: 'pageName', // name for page. Default is "page" with index, such as "page0".
  renderHtml: `<div class="page-wrapper">page</div>`, // Html structure under swiper-slide
  pageEnter: () => console.log('enter page'), // Hook function for enter the page
  pageLeave: () => console.log('leave page'), // Hook function for leave the page
})
```

##### Use Page extends (recommended)

```javascript
import { Page } from '@cycjimmy/h5-pages'

const page = new class extends Page {
  constructor() {
    super({
      name: 'page',
      renderHtml: `<div class="page-wrapper">page</div>`,
      pageEnter: () => console.log('enter page'),
      pageLeave: () => console.log('leave page'),
    })
  }

  // paramInit(): [Option] Add your custom parameters.
  paramInit() {
    // In this function super.paramInit() must be called first.
    super.paramInit()

    // It is recommended to place your custom parameters here.
    this.oneCustomElement = this.page.querySelector(`.one-custom-element`)
  }

  // eventBind(): [Option] Add your custom event bindings.
  eventBind() {
    // In this function super.eventBind() must be called first.
    super.eventBind()

    // It is recommended to place custom event bindings here.
    this.oneCustomElement.addEventListener('click', () => {
      console.log('oneCustomElement clicked')
    })
  }

  // extraRender(): [Option] Add your custom action When the page loaded.
  extraRender() {
    console.log('pageLoaded')
  }

  // Other custom extensions
  // ...
}()
```

#### `Page` instance Properties

* `name`: The name of the Page instance.
* `root`: H5 root element. Same as `h5Pages.root`.
* `swiper`: Main swiper instance for H5. Same as `h5Pages.swiper`.
* `page`: The root element of the page instance, which is the `swiper-slide` element.
* `pageIndex`: The index of the page instance, the same as `realIndex` for swiper.

### Popup

#### Use Popup extends to Build a Popup

```javascript
import { Popup } from '@cycjimmy/h5-pages'

const popup = new class extends Popup {
  load() {
    // You must Overwrite this function with your own function
  }

  // Other custom extensions
  // ...
}()
```

#### `Popup` Instance Methods

* `load()`: Load(Show off) the popup. You must Overwrite this function with your own function. It may return nothing or a `Promise<void>`.
* `render(htmlText)`: Render custom html texts and add the popup to the root element of h5 page.
* `remove()`: Remove the popup from the root element of h5 page.

#### `Popup` instance Properties

* `root`: H5 root element. Same as `h5Pages.root`.
* `popup`: The root element of the popup instance.

## CDN
[![jsdelivr][jsdelivr-image]][jsdelivr-url]

To use via a CDN include this in your HTML:

```text
<script src="https://cdn.jsdelivr.net/npm/@cycjimmy/h5-pages@5/dist/h5-pages.umd.min.js"></script>
```

The UMD build exposes the global `h5Pages`, the same named exports as the ESM
entry (`Page`, `Popup`, `init`, `getPageByName`, `changePageTo`, `h5Pages`).

<!-- Links: -->
[npm-image]: https://img.shields.io/npm/v/@cycjimmy/h5-pages
[npm-url]: https://npmjs.org/package/@cycjimmy/h5-pages
[npm-bundle-size-image]: https://img.shields.io/bundlephobia/min/@cycjimmy/h5-pages

[download-image]: https://img.shields.io/npm/dt/@cycjimmy/h5-pages
[download-url]: https://npmjs.org/package/@cycjimmy/h5-pages

[jsdelivr-image]: https://img.shields.io/jsdelivr/npm/hy/@cycjimmy/h5-pages
[jsdelivr-url]: https://www.jsdelivr.com/package/npm/@cycjimmy/h5-pages

[workflows-badge-image]: https://github.com/cycjimmy/h5-pages/workflows/Test%20CI/badge.svg
[workflows-url]: https://github.com/cycjimmy/h5-pages/actions/workflows/nodeTestCI.yml

[libraries-status-image]: https://img.shields.io/librariesio/release/npm/@cycjimmy/h5-pages
[libraries-sourcerank-image]: https://img.shields.io/librariesio/sourcerank/npm/@cycjimmy/h5-pages
[libraries-status-url]: https://libraries.io/github/cycjimmy/h5-pages
[libraries-sourcerank-url]: https://libraries.io/npm/@cycjimmy%2Fh5-pages

[coverage-image]: https://img.shields.io/coveralls/github/cycjimmy/h5-pages
[coverage-url]: https://coveralls.io/github/cycjimmy/h5-pages

[release-date-image]: https://img.shields.io/github/release-date/cycjimmy/h5-pages
[release-url]: https://github.com/cycjimmy/h5-pages/releases

[vite-image]: https://img.shields.io/github/package-json/dependency-version/cycjimmy/h5-pages/dev/vite
[vite-url]: https://github.com/vitejs/vite

[semantic-image]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%20%F0%9F%9A%80-semantic--release-e10079.svg
[semantic-url]: https://github.com/semantic-release/semantic-release

[vitest-image]: https://img.shields.io/badge/tested_with-vitest-6e9f18.svg
[vitest-url]: https://vitest.dev/

[license-image]: https://img.shields.io/npm/l/@cycjimmy/h5-pages

[github-pages-url]: https://cycjimmy.github.io/h5-pages/

[Readme-url-En]: https://github.com/cycjimmy/h5-pages/blob/main/README.md
[Readme-url-ZhCN]: https://github.com/cycjimmy/h5-pages/blob/main/README_zhCN.md

---
_Source: https://npm.io/package/@cycjimmy/h5-pages · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
