Pagination

Quick first, previous, next, last, and page buttons for pagination control of another component (such as <b-table> or lists).

Overview

<b-pagination> is a custom input component that provides a current page number input control. The value should be bound via v-model in your app. Page numbers are indexed from 1. The number of pages is computed from the provided prop values for total-rows and per-page.

For pagination that changes to a new URL, use the <b-pagination-nav> component instead.

Example Usage with <b-table>:

<template>
  <div class="overflow-auto">
    <b-pagination
      v-model="currentPage"
      :total-rows="rows"
      :per-page="perPage"
      aria-controls="my-table"
    ></b-pagination>

    <p class="mt-3">Current Page: {{ currentPage }}</p>

    <b-table
      id="my-table"
      :items="items"
      :per-page="perPage"
      :current-page="currentPage"
      small
    ></b-table>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        perPage: 3,
        currentPage: 1,
        items: [
          { id: 1, first_name: 'Fred', last_name: 'Flintstone' },
          { id: 2, first_name: 'Wilma', last_name: 'Flintstone' },
          { id: 3, first_name: 'Barney', last_name: 'Rubble' },
          { id: 4, first_name: 'Betty', last_name: 'Rubble' },
          { id: 5, first_name: 'Pebbles', last_name: 'Flintstone' },
          { id: 6, first_name: 'Bamm Bamm', last_name: 'Rubble' },
          { id: 7, first_name: 'The Great', last_name: 'Gazzoo' },
          { id: 8, first_name: 'Rockhead', last_name: 'Slate' },
          { id: 9, first_name: 'Pearl', last_name: 'Slaghoople' }
        ]
      }
    },
    computed: {
      rows() {
        return this.items.length
      }
    }
  }
</script>

<!-- b-pagination.vue -->

Customizing appearance

<b-pagination> supports several props/slots that allow you to customize the appearance. All *-text props are text-only and strip out HTML but you can use their equally named slot counterparts for that.

Limiting the number of displayed buttons

To restrict the number of page buttons (including the ellipsis, but excluding the first, prev, next, and last buttons) shown, use the limit prop to specify the desired number of page buttons (including the ellipsis, if shown). The default limit is 5. The minimum supported value is 3. When limit is set to 3, no ellipsis indicators will be shown for practical purposes.

The first and last buttons can be optionally hidden by setting the hide-goto-end-buttons prop.

The showing of the ellipsis can be optionally disabled by setting the hide-ellipsis prop.

Small screen support

On smaller screens (i.e. mobile), some of the <b-pagination> buttons will be hidden to minimize the potential of the pagination interface wrapping onto multiple lines:

  • The ellipsis indicators will be hidden on screens xs and smaller.
  • Page number buttons will be limited to a maximum of 3 visible on xs screens and smaller.

This ensures that no more than 3 page number buttons are visible, along with the goto first, prev, next, and last buttons.

Button content

For a full list of all available slots see the Slots section below.

<template>
  <div class="overflow-auto">
    <!-- Use text in props -->
    <b-pagination
      v-model="currentPage"
      :total-rows="rows"
      :per-page="perPage"
      first-text="First"
      prev-text="Prev"
      next-text="Next"
      last-text="Last"
    ></b-pagination>

    <!-- Use emojis in props -->
    <b-pagination
      v-model="currentPage"
      :total-rows="rows"
      :per-page="perPage"
      first-text="⏮"
      prev-text="⏪"
      next-text="⏩"
      last-text="⏭"
      class="mt-4"
    ></b-pagination>

    <!-- Use HTML and sub-components in slots -->
    <b-pagination
      v-model="currentPage"
      :total-rows="rows"
      :per-page="perPage"
      class="mt-4"
    >
      <template #first-text><span class="text-success">First</span></template>
      <template #prev-text><span class="text-danger">Prev</span></template>
      <template #next-text><span class="text-warning">Next</span></template>
      <template #last-text><span class="text-info">Last</span></template>
      <template #ellipsis-text>
        <b-spinner small type="grow"></b-spinner>
        <b-spinner small type="grow"></b-spinner>
        <b-spinner small type="grow"></b-spinner>
      </template>
      <template #page="{ page, active }">
        <b v-if="active">{{ page }}</b>
        <i v-else>{{ page }}</i>
      </template>
    </b-pagination>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        rows: 100,
        perPage: 10,
        currentPage: 1
      }
    }
  }
</script>

<!-- b-pagination-appearance.vue -->

The slot page is always scoped, while the slots first-text, prev-text, next-text and last-text are optionally scoped. The ellipsis-text slot is not scoped.

Scoped variables properties available to the page slot:

Property Type Description
page Number Page number (from 1 to numberOfPages)
index Number Page number (indexed from 0 to numberOfPages -1)
active Boolean If the page is the active page
disabled Boolean If the page button is disabled
content String Page number as a string

Scoped variables properties available to the first-text, prev-text, next-text and last-text slots:

Property Type Description
page Number Page number (from 1 to numberOfPages)
index Number Page number (indexed from 0 to numberOfPages -1)
disabled Boolean If the page button is disabled

Goto first/last button type

If you prefer to have buttons with the first and last page number to go to the corresponding page, use the first-number and last-number props.

<template>
  <div class="overflow-auto">
    <div>
      <h6>Goto first button number</h6>
      <b-pagination
        v-model="currentPage"
        :total-rows="rows"
        :per-page="perPage"
        first-number
      ></b-pagination>
    </div>

    <div class="mt-3">
      <h6>Goto last button number</h6>
      <b-pagination
        v-model="currentPage"
        :total-rows="rows"
        :per-page="perPage"
        last-number
      ></b-pagination>
    </div>

    <div class="mt-3">
      <h6>Goto first and last button number</h6>
      <b-pagination
        v-model="currentPage"
        :total-rows="rows"
        :per-page="perPage"
        first-number
        last-number
      ></b-pagination>
    </div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        rows: 100,
        perPage: 1,
        currentPage: 5
      }
    }
  }
</script>

<!-- b-pagination-goto-first-last-number.vue -->

Button size

Optionally change from the default button size by setting the size prop to either 'sm' for smaller buttons or 'lg' for larger buttons.

<template>
  <div class="overflow-auto">
    <div>
      <h6>Small</h6>
      <b-pagination v-model="currentPage" :total-rows="rows" size="sm"></b-pagination>
    </div>

    <div class="mt-3">
      <h6>Default</h6>
      <b-pagination v-model="currentPage" :total-rows="rows"></b-pagination>
    </div>

    <div class="mt-3">
      <h6>Large</h6>
      <b-pagination v-model="currentPage" :total-rows="rows" size="lg"></b-pagination>
    </div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        rows: 100,
        currentPage: 1
      }
    }
  }
</script>

<!-- b-pagination-size.vue -->

Pill style

Easily switch to pill style buttons by setting the pills prop

<template>
  <div class="overflow-auto">
    <div>
      <h6>Small Pills</h6>
      <b-pagination v-model="currentPage" pills :total-rows="rows" size="sm"></b-pagination>
    </div>

    <div class="mt-3">
      <h6>Default Pills</h6>
      <b-pagination v-model="currentPage" pills :total-rows="rows"></b-pagination>
    </div>

    <div class="mt-3">
      <h6>Large Pills</h6>
      <b-pagination v-model="currentPage" pills :total-rows="rows" size="lg"></b-pagination>
    </div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        rows: 100,
        currentPage: 1
      }
    }
  }
</script>

<!-- b-pagination-pills.vue -->

Note: Pill styling requires BootstrapVue's custom CSS/SCSS.

Alignment

By default the pagination component is left aligned. Change the alignment to center, right (right is an alias for end), or fill by setting the prop align to the appropriate value.

<template>
  <div class="overflow-auto">
    <div>
      <h6>Left alignment (default)</h6>
      <b-pagination v-model="currentPage" :total-rows="rows"></b-pagination>
    </div>

    <div class="mt-3">
      <h6 class="text-center">Center alignment</h6>
      <b-pagination v-model="currentPage" :total-rows="rows" align="center"></b-pagination>
    </div>

    <div class="mt-3">
      <h6 class="text-right">Right (end) alignment</h6>
      <b-pagination v-model="currentPage" :total-rows="rows" align="right"></b-pagination>
    </div>

    <div class="mt-3">
      <h6 class="text-center">Fill alignment</h6>
      <b-pagination v-model="currentPage" :total-rows="rows" align="fill"></b-pagination>
    </div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        rows: 100,
        currentPage: 3
      }
    }
  }
</script>

<!-- b-pagination-alignment.vue -->

Preventing a page from being selected

You can listen for the page-click event, which provides an option to prevent the page from being selected. The event is emitted with two arguments:

  • bvEvent: The BvEvent object. Call bvEvent.preventDefault() to cancel page selection
  • page: Page number to select (starting with 1)

For accessibility reasons, when using the page-click event to prevent a page from being selected, you should provide some means of notification to the user as to why the page is not able to be selected. It is recommended to use the disabled attribute on the <b-pagination> component instead of using the page-click event (as disabled is more intuitive for screen reader users).

Accessibility

The <b-pagination> component provides many features to support assistive technology users, such as aria- attributes and keyboard navigation.

aria-controls

When pagination is controlling another component on the page (such as <b-table>), set the aria-controls prop to the id of the element it is controlling. This will help non-sighted users know what component is being updated/controlled.

ARIA labels

<b-pagination> provides various *-label-* props which are used to set the aria-label attributes on the various elements within the component, which will help users of assistive technology.

Prop aria-label content default
label-first-page "Goto first page"
label-prev-page "Goto previous page"
label-next-page "Goto next page"
label-last-page "Goto last page"
label-page "Goto page", appended with the page number
aria-label "Pagination", applied to the outer pagination container

The label-page will optionally accept a function to generate the aria-label. The function is passed a single argument which is the page number (indexed from 1 to number of pages).

You can remove any label by setting the prop to an empty string (''), although this is not recommended unless the content of the button textually conveys its purpose.

Keyboard navigation support

<b-pagination> supports keyboard navigation out of the box, and follows the WAI-ARIA roving tabindex pattern.

  • Tabbing into the pagination component will autofocus the current active page button
  • Left (or Up) and Right (or Down) arrow keys will focus the previous and next buttons, respectively, in the page list
  • Enter or Space keys will select (click) the currently focused page button
  • Pressing Tab will move to the next control or link on the page, while pressing Shift+Tab will move to the previous control or link on the page.

See also

For navigation based pagination, please see the <b-pagination-nav> component.

Component reference

<b-pagination>

Properties

All property default values are globally configurable.

Property
(Click to sort ascending)
Type
(Click to sort ascending)
Default
Description
align
String'left'Alignment of the page buttons: 'start' (or 'left'), 'center', 'end' (or 'right'), or 'fill'
aria-controls
StringIf this component controls another component or element, set this to the ID of the controlled component or element
aria-label
String'Pagination'Value to place in the 'aria-label' attribute of the pagination control
disabled
BooleanfalseWhen set to `true`, disables the component's functionality and places it in a disabled state
ellipsis-class
v2.3.0+
Array or Object or StringClass(es) to apply to the 'ellipsis' placeholders
ellipsis-text
String'…'Content to place in the ellipsis placeholder
first-class
v2.3.0+
Array or Object or StringClass(es) to apply to the 'Go to first page' button
first-number
v2.3.0+
BooleanfalseDisplay first page number instead of Goto First button
first-text
String'«'Content to place in the goto first page button
hide-ellipsis
BooleanfalseDo not show ellipsis buttons
hide-goto-end-buttons
BooleanfalseHides the goto first and goto last page buttons
label-first-page
String'Go to first page'Value to place in the 'aria-label' attribute of the goto first page button
label-last-page
String'Go to last page'Value to place in the 'aria-label' attribute of the goto last page button
label-next-page
String'Go to next page'Value to place in the 'aria-label' attribute of the goto next page button
label-page
Function or String'Go to page'Value to place in the 'aria-label' attribute of the goto page button. Page number will be prepended automatically
label-prev-page
String'Go to previous page'Value to place in the 'aria-label' attribute of the goto previous page button
last-class
v2.3.0+
Array or Object or StringClass(es) to apply to the 'Go to last page' button
last-number
v2.3.0+
BooleanfalseDisplay last page number instead of Goto Last button
last-text
String'»'Content to place in the goto last page button
limit
Number or String5Maximum number of buttons to show (including ellipsis if shown, but excluding the bookend buttons)
next-class
v2.3.0+
Array or Object or StringClass(es) to apply to the 'Go to next page' button
next-text
String'›'Content to place in the goto next page button
page-class
v2.3.0+
Array or Object or StringClass(es) to apply to the 'Go to page #' buttons
per-page
Number or String20Number of rows per page
pills
v2.1.0+
BooleanfalseApplies pill styling to the pagination buttons
prev-class
v2.3.0+
Array or Object or StringClass(es) to apply to the 'Go to previous page' button
prev-text
String'‹'Content to place in the goto previous page button
size
StringSize of the rendered buttons: 'sm', 'md' (default), or 'lg'
total-rows
Number or String0Total number of rows in the dataset
value
v-model
Boolean or Number or StringnullCurrent page number, starting from 1

v-model

Property
Event
valueinput

Slots

Name
Scoped
Description
ellipsis-text NoThe '...' indicator content. Overrides the `ellipsis-text` prop
first-text The 'Go to first page' button content
last-text The 'Go to last page' button content
next-text The 'Go to next page' button content
page Page number button content
prev-text The 'Go to previous page' button content

Events

Event
Arguments
Description
change
  1. page - Selected page number (starting with `1`)
Emitted when page changes via user interaction
input
  1. page - Selected page number (starting with `1`), or `null` if no page found
Emitted when page changes via user interaction or programmatically
page-click v2.17.0+
  1. bvEvent - The `BvEvent` object. Call `bvEvent.preventDefault()` to cancel page selection
  2. page - Page number to select (starting with `1`)
Emitted when a page button was clicked. Cancelable

Importing individual components

You can import individual components into your project via the following named exports:

Component
Named Export
Import Path
<b-pagination>BPaginationbootstrap-vue

Example:

import { BPagination } from 'bootstrap-vue'
Vue.component('b-pagination', BPagination)

Importing as a Vue.js plugin

This plugin includes all of the above listed individual components. Plugins also include any component aliases.

Named Export
Import Path
PaginationPluginbootstrap-vue

Example:

import { PaginationPlugin } from 'bootstrap-vue'
Vue.use(PaginationPlugin)