Pagination

If you have too much data to display in one page, use pagination.

Basic usage

Set layout with different pagination elements you wish to display separated with a comma. Pagination elements are: prev (a button navigating to the previous page), next (a button navigating to the next page), pager (page list), jumper (a jump-to input), total (total item count), sizes (a select to determine page size) and ->(every element after this symbol will be pulled to the right).

When you have few pages

When you have more than 7 pages

Number of pagers

By default, Pagination collapses extra pager buttons when it has more than 7 pages. This can be configured with the pager-count attribute.

Buttons with background color

Set the background attribute and the buttons will have a background color.

Small Pagination

Use small pagination in the case of limited space.

set size to change the size. Here is a demonstration of small

Hide pagination when there is only one page

When there is only one page, hide the pagination by setting the hide-on-single-page attribute.

More elements

Add more modules based on your scenario.

This example is a complete use case. It uses size-change and current-change event to handle page size changes and current page changes. page-sizes accepts an array of integers, each of which represents a different page size in the sizes select options, e.g. [100, 200, 300, 400] indicates that the select will have four options: 100, 200, 300 or 400 items per page.

Total item count

Total 1000

Change page size

Jump to

Go to

All combined

Total 400

Go to

vue

<template>
  <div class="flex items-center mb-4">
    <el-radio-group v-model="size" class="mr-4">
      <el-radio-button value="default">default</el-radio-button>
      <el-radio-button value="large">large</el-radio-button>

      <el-radio-button value="small">small</el-radio-button>
    </el-radio-group>
    <div>
      background:
      <el-switch v-model="background" class="ml-2" />
    </div>
    <div class="ml-4">
      disabled: <el-switch v-model="disabled" class="ml-2" />
    </div>
  </div>

  <hr class="my-4" />

  <div class="demo-pagination-block">
    <div class="demonstration">Total item count</div>
    <el-pagination
      v-model:current-page="currentPage1"
      :page-size="100"
      :size="size"
      :disabled="disabled"
      :background="background"
      layout="total, prev, pager, next"
      :total="1000"
      @size-change="handleSizeChange"
      @current-change="handleCurrentChange"
    />
  </div>
  <div class="demo-pagination-block">
    <div class="demonstration">Change page size</div>
    <el-pagination
      v-model:current-page="currentPage2"
      v-model:page-size="pageSize2"
      :page-sizes="[100, 200, 300, 400]"
      :size="size"
      :disabled="disabled"
      :background="background"
      layout="sizes, prev, pager, next"
      :total="1000"
      @size-change="handleSizeChange"
      @current-change="handleCurrentChange"
    />
  </div>
  <div class="demo-pagination-block">
    <div class="demonstration">Jump to</div>
    <el-pagination
      v-model:current-page="currentPage3"
      v-model:page-size="pageSize3"
      :size="size"
      :disabled="disabled"
      :background="background"
      layout="prev, pager, next, jumper"
      :total="1000"
      @size-change="handleSizeChange"
      @current-change="handleCurrentChange"
    />
  </div>
  <div class="demo-pagination-block">
    <div class="demonstration">All combined</div>
    <el-pagination
      v-model:current-page="currentPage4"
      v-model:page-size="pageSize4"
      :page-sizes="[100, 200, 300, 400]"
      :size="size"
      :disabled="disabled"
      :background="background"
      layout="total, sizes, prev, pager, next, jumper"
      :total="400"
      @size-change="handleSizeChange"
      @current-change="handleCurrentChange"
    />
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

import type { ComponentSize } from 'element-plus'

const currentPage1 = ref(5)
const currentPage2 = ref(5)
const currentPage3 = ref(5)
const currentPage4 = ref(4)
const pageSize2 = ref(100)
const pageSize3 = ref(100)
const pageSize4 = ref(100)
const size = ref<ComponentSize>('default')
const background = ref(false)
const disabled = ref(false)

const handleSizeChange = (val: number) => {
  console.log(`${val} items per page`)
}
const handleCurrentChange = (val: number) => {
  console.log(`current page: ${val}`)
}
</script>

<style scoped>
.demo-pagination-block + .demo-pagination-block {
  margin-top: 10px;
}
.demo-pagination-block .demonstration {
  margin-bottom: 16px;
}
</style>

API

Attributes

Name	Description	Type	Default
size 2.7.6	pagination size	`enum`	'default'
background	whether the buttons have a background color	`boolean`	false
page-size / v-model:page-size	item count of each page	`number`	—
default-page-size	default initial value of page size, not setting is the same as setting 10	`number`	—
total	total item count	`number`	—
page-count	total page count. Set either `total` or `page-count` and pages will be displayed; if you need `page-sizes`, `total` is required	`number`	—
pager-count	number of pagers. Pagination collapses when the total page count exceeds this value	`number`	7
current-page / v-model:current-page	current page number	`number`	—
default-current-page	default initial value of current-page, not setting is the same as setting 1	`number`	—
layout	layout of Pagination, elements separated with a comma	`string`	prev, pager, next, jumper, ->, total
page-sizes	options of item count per page	`object`	[10, 20, 30, 40, 50, 100]
append-size-to 2.8.4	which element the size dropdown appends to	`string`	—
popper-class	custom class name for the page size Select's dropdown	`string`	''
popper-style 2.11.5	custom style for the page size Select's dropdown	`string` / `object`	—
prev-text	text for the prev button	`string`	''
prev-icon	icon for the prev button, has a lower priority than `prev-text`	`string` / `Component`	ArrowLeft
next-text	text for the next button	`string`	''
next-icon	icon for the next button, has a lower priority than `next-text`	`string` / `Component`	ArrowRight
disabled	whether Pagination is disabled	`boolean`	false
teleported 2.3.13	whether Pagination select dropdown is teleported to the body	`boolean`	true
hide-on-single-page	whether to hide when there's only one page	`boolean`	false
small deprecated	whether to use small pagination	`boolean`	false

WARNING

We'll detect some deprecated usages, if your pagination don't appeared or worked as expected, please check rules below:

You have to define one of total and page-count, otherwise we can't determine count of total pages.When both defined, page-count taken as priority.
If current-page is defined, you have to listen current-page change, by also define @update:current-page, otherwise pagination didn't work.
If page-size is defined while page size selector displayed(sizes included in layout), you have to listen page-size change as well, by define @update:page-size, otherwise change of page size didn't work.

Events

Name	Description	Type
size-change	triggers when `page-size` changes	`Function`
current-change	triggers when `current-page` changes	`Function`
change 2.4.4	triggers when `current-page` or `page-size` changes	`Function`
prev-click	triggers when the prev button is clicked and current page changes	`Function`
next-click	triggers when the next button is clicked and current page changes	`Function`