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), size (a select to determine page size) and ->(every element after this symbol will be pulled to the right).

When you have few pages

Showing from 1 — 10 of 50 result(s)

When you have more than 7 pages

Showing from 1 — 10 of 1000 result(s)

---

<template>
  <div>
    <p>When you have few pages</p>
    <b-pagination :total="50" />
  </div>
  <div class="mt-4">
    <p>When you have more than 7 pages</p>
    <b-pagination :total="1000" />
  </div>
</template>

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.

Showing from 1 — 10 of 1000 result(s)

---

<template>
  <b-pagination :pager-count="5" :total="1000" />
</template>

Auto Hide

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

Show

Hide

Showing from 1 — 5 of 5 result(s)

---

<template>
  <div>
    <b-switch v-model="value" small active-text="Hide" inactive-text="Show" />
    <b-divider class="my-2" />
    <b-pagination :hide-on-single-page="value" :total="5" />
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const value = ref(false)
</script>

Custom layout

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.

DefaultSmall

Background

Disabled

Total item count

Showing from 401 — 500 of 1000 result(s)

Change page size

Jump to

Go to

All combined

Showing from 301 — 400 of 400 result(s)

Go to

---

<template>
  <div class="flex items-center">
    <b-radio-group v-model="small" size="small">
      <b-radio-button :value="false">Default</b-radio-button>
      <b-radio-button :value="true">Small</b-radio-button>
    </b-radio-group>
    <b-switch
      v-model="background"
      small
      active-text="Background"
      class="ml-4"
    />
    <b-switch v-model="disabled" small active-text="Disabled" class="ml-4" />
  </div>

  <b-divider />

  <p>Total item count</p>
  <b-pagination
    v-model:currentPage="currentPage1"
    :page-size="100"
    :small="small"
    :disabled="disabled"
    :background="background"
    layout="total, prev, pager, next"
    :total="1000"
    @size-change="handleSizeChange"
    @current-change="handleCurrentChange"
  />

  <b-divider />

  <p>Change page size</p>
  <b-pagination
    v-model:currentPage="currentPage2"
    v-model:page-size="pageSize2"
    :page-sizes="[100, 200, 300, 400]"
    :small="small"
    :disabled="disabled"
    :background="background"
    layout="sizes, prev, pager, next"
    :total="1000"
    @size-change="handleSizeChange"
    @current-change="handleCurrentChange"
  />
  <b-divider />
  <p>Jump to</p>
  <b-pagination
    v-model:currentPage="currentPage3"
    v-model:page-size="pageSize3"
    :small="small"
    :disabled="disabled"
    :background="background"
    layout="prev, pager, next, jumper"
    :total="1000"
    @size-change="handleSizeChange"
    @current-change="handleCurrentChange"
  />
  <b-divider />
  <p>All combined</p>
  <b-pagination
    v-model:currentPage="currentPage4"
    v-model:page-size="pageSize4"
    :page-sizes="[100, 200, 300, 400]"
    :small="small"
    :disabled="disabled"
    :background="background"
    layout="total, sizes, prev, pager, next, jumper"
    :total="400"
    @size-change="handleSizeChange"
    @current-change="handleCurrentChange"
  />
</template>

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

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 small = ref(false)
const background = ref(false)
const disabled = ref(false)

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

Attributes

Attribute	Description	Type	Accepted Values	Default
page-size	item count of each page, supports the v-model bidirectional binding	number	—	10
default-page-size	default initial value of page size	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	odd number between 5 and 21	7
current-page	current page number, supports the v-model bidirectional binding	number	—	1
default-current-page	default initial value of current-page	number	—	—
layout	layout of Pagination, elements separated with a comma	string	sizes / prev / pager / next / jumper / -> / total / slot	'prev, pager, next, jumper, ->, total'
page-sizes	options of item count per page	number[]	—	[10, 20, 30, 40, 50, 100]
disabled	whether Pagination is disabled	boolean	—	false
hide-on-single-page	whether to hide when there's only one page	boolean	—	—

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

Event Name	Description	Parameters
size-change	triggers when page-size changes	the new page size
current-change	triggers when current-page changes	the new current page
prev-click	triggers when the prev button is clicked and current page changes	the new current page
next-click	triggers when the next button is clicked and current page changes	the new current page

WARNING

Events above are not recommended(but are still supported for compatible reason), better choice is to use the two-way data binding by v-model.

Slots

Name	Description
—	custom content. To use this, you need to declare slot in layout