Pagination

17:06

Description

A pagination control made of Prev / Next buttons and a "current / total pages" text in the middle: v-model binds the current page, while total and page-size derive the total page count (ceil(total / pageSize)). Turning a page writes back to v-model and emits change({ type, current }); the button for the first or last page is automatically greyed out and disabled.

Compatibility

Platform	Support
App	✅ Supported (the page-number text declares color and font size directly on text, working around App's text not inheriting parent styles)
H5	✅ Supported
WeChat Mini Program	✅ Supported

Examples

Basic Usage

Bind current page via v-model; total and page-size calculate total pages.

View source

<template>
    <ux-pagination v-model="current" :total="50" :page-size="5"></ux-pagination>
</template>

<script setup lang="uts">
const current = ref<number>(1);
</script>

Icon Buttons

show-icon displays left/right arrow icon buttons.

View source

<template>
    <ux-pagination v-model="current" :total="50" :page-size="5" show-icon></ux-pagination>
</template>

<script setup lang="uts">
const current = ref<number>(1);
</script>

Custom Text

Customize button text via prev-text and next-text.

View source

<template>
    <ux-pagination v-model="current" :total="50" :page-size="5" prev-text="Prev" next-text="Next"></ux-pagination>
</template>

<script setup lang="uts">
const current = ref<number>(1);
</script>

Custom Style

Customize pagination container style via custom-style.

View source

<template>
    <ux-pagination v-model="current" :total="50" :page-size="5" show-icon :custom-style="customStyle"></ux-pagination>
</template>

<script setup lang="uts">
import { createStyle } from '@/uni_modules/uview-pro-x';

const current = ref<number>(1);

const customStyle = computed<UTSJSONObject>((): UTSJSONObject => {
    const style = createStyle();
    style['backgroundColor'] = '#f5f5f5';
    style['paddingTop'] = '10px';
    style['paddingBottom'] = '10px';
    style['paddingLeft'] = '10px';
    style['paddingRight'] = '10px';
    style['borderRadius'] = '6px';
    return style;
});
</script>

Change Event

Listen to change event for pagination direction and current page.

View source

<template>
    <ux-pagination v-model="current" :total="50" :page-size="5" show-icon @change="onChange"></ux-pagination>
    <text class="result">当前页: {{ current }} / {{ totalPages }}</text>
</template>

<script setup lang="uts">
const current = ref<number>(1);
const totalPages = Math.ceil(50 / 5);

function onChange(payload: UTSJSONObject): void {
    const page = payload['current'] as number;
    const type = payload['type'] as string;
    uni.showToast({ title: type + ' → ' + page, icon: 'none' });
}
</script>

<style scoped>
.result {
    margin-top: 10px;
    font-size: 13px;
    color: #909399;
}
</style>

API

Props

Property	Description	Type	Default	Version
customStyle	Custom root element style	UTSJSONObject	-	-
customClass	Custom root element style class	string	''	-
modelValue	Current page, bound with v-model	number	1	-
prevText	Previous button text; defaults to the locale key uPagination.prevText	string	''	-
nextText	Next button text; defaults to the locale key uPagination.nextText	string	''	-
total	Total number of records, used to derive the page count	number	0	-
pageSize	Records per page	number	10	-
showIcon	Whether to use icons instead of text buttons	boolean	false	-
prevIcon	Icon name for the previous button	string	'arrow-left'	-
nextIcon	Icon name for the next button	string	'arrow-right'	-

Events

Event	Description	Params	Version
change	Fires when the page changes; the payload contains type (prev / next) and current (the new page)	payload: UTSJSONObject	-

Slots

Slot	Description	Version
default	Middle page-number area, showing "current / total pages" by default	-

Notes

1. The page number is not clamped automatically: turning a page is just ±1 and only the button disabled stops it. If total / page-size shrink the page count while the current page stays high, current is not rolled back.
2. When page-size <= 0 the page count is computed with 10; when total <= 0 the page count is 0, so current (≥1) is already not below it and the Next button is disabled outright.
3. Bind the page with v-model (or :model-value + @update:model-value). The change payload is a UTSJSONObject, so reading current / type needs an as cast (see the example).
4. With show-icon, the buttons render prev-icon / next-icon and prev-text / next-text are no longer shown.
5. Default button text comes from the locale keys uPagination.prevText / nextText, overridden by prev-text / next-text.
6. The middle "current / total pages" area is the default slot and can be replaced entirely.