Pagination Navigation

Quick first, previous, next, last, and page buttons for navigation based pagination, supporting regular links or router links.

<b-pagination-nav> is used for navigating to new page URLs. For controlling in page component pagination (such as table or list pagination), use the <b-pagination> component instead.

<template>
  <div class="overflow-auto">
    <div>
      <h6>Default</h6>
      <b-pagination-nav base-url="#" :number-of-pages="10" v-model="currentPage" />
    </div>

    <div class="mt-3">
      <h6 class="mt-4">With link generator function</h6>
      <b-pagination-nav :link-gen="linkGen" :number-of-pages="10" v-model="currentPage" />
    </div>

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

<script>
  export default {
    data() {
      return {
        currentPage: 1
      }
    },
    methods: {
      linkGen(pageNum) {
        return '#page/' + pageNum + '/foobar'
      }
    }
  }
</script>

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

<b-pagination-nav> is a custom input component that provides navigational pagination. The current page should be set via the value prop (or v-model), and the total number of pages set with number-of-pages. Page numbers are indexed from 1 through number-of-pages.

Current page

You should always set the current page number by setting the prop value (or using v-model) to ensure that correct active page number is highlighted.

By default, <b-pagination-nav> generates plain link tags, setting the HREF attribute to base-url concatenated with the page number. The base-url prop defaults to '/'.

To generate page links as <router link> components, set the use-router prop. The HREF will then become the to prop of the router link.

If you need finer grained control over the generated link URLs or <router-link> to props, you may set the link-gen prop to a function reference that accepts one argument which is a page number. The link-gen function should return either a string (for HREF) or a router to object. If the returned value is an object, then a router-link will always be generated. If the return value is a string, a link is generated by default unless the use-router prop is set.

// For regular HREF (or string `to` prop if `use-router` is set)
linkGen(pageNum) {
  return '/foo/page/' + pageNum
}

// Returning a router-link `to` object
linkGen(pageNum) {
  return {
    path: '/foo/page/' + pageNum
  }
}

Page number generation

By default, <b-pagination-nav> renders page numbers (1-N) in the page link buttons. You can override this behaviour by supplying a function reference to the page-gen property. The function reference should accept a single argument which is a page number (1-N). The page-gen function should return a string.

Note: HTML content in generated page number strings is not supported.

Example: Using an array of links to generate pagination:

<template>
  <div class="overflow-auto">
    <b-pagination-nav
      :link-gen="linkGen"
      :page-gen="pageGen"
      :number-of-pages="links.length"
      v-model="currentPage"
    />

    <div class="mt-3">
      Page: {{ currentPage }}<br />
      Page Link: {{ pageLink }}
    </div>
  </div>
</template>

<script>
  export default {
    computed: {
      pageLink() {
        return this.linkGen(this.currentPage)
      }
    },
    data() {
      return {
        currentPage: 1,
        links: ['#foo', '#bar', '#baz', '#faz']
      }
    },
    methods: {
      linkGen(pageNum) {
        return this.links[pageNum - 1]
      },
      pageGen(pageNum) {
        return this.links[pageNum - 1].slice(1)
      }
    }
  }
</script>

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

Button Size

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

<template>
  <div class="overflow-auto">
    <div>
      <h6>Small</h6>
      <b-pagination-nav size="sm" base-url="#" :number-of-pages="5" v-model="currentPage" />
    </div>

    <div class="mt-3">
      <h6>Default</h6>
      <b-pagination-nav base-url="#" :number-of-pages="5" v-model="currentPage" />
    </div>

    <div class="mt-3">
      <h6>Large</h6>
      <b-pagination-nav size="lg" base-url="#" :number-of-pages="5" v-model="currentPage" />
    </div>

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

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

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

Customizing

<b-pagination-nav> supports several props that allow you to customize the appearance.

Prop Description
limit Limit the maximum number of displayed page buttons (including ellipsis if present, and excluding first/prev/next/last buttons)
number-of-pages The total number of pages
hide-ellipsis never show ellipsis indicators
hide-goto-end-buttons never display goto first/last buttons

And provides several props for setting the content of the bookend buttons:

Prop Description
first-text The "goto first page" button text (plain html supported)
prev-text The "goto previous page" button text (plain html supported)
next-text The "goto next page" button text (plain html supported)
last-text The "goto last page" button text (plain html supported)
ellipsis-text the ... indicator text (plain html supported)

Ellipsis indicator(s) will only be ever shown at the front and/or end of the page number buttons. For limit values less than or equal to 3, the ellipsis indicator(s) will never be shown for practical display reasons.

Note: HTML is supported via the bookend content props. If allowing user supplied content to populate these props, you should use named slots (see below) instead to avoid possible XSS attacks.

Named slots

<b-pagination-nav> supports several slots that allow you to customize the appearance.

Slot Description
first-text The "goto first page" button text (html/sub-components supported)
prev-text The "goto previous page" button text (html/sub-components supported)
next-text The "goto next page" button text (html/sub-components supported)
last-text The "goto last page" button text (html/sub-components supported)
ellipsis-text the ... indicator text (html/sub-components supported)

Alignment

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

<template>
  <div class="overflow-auto">
    <div>
      <h6>Left alignment (default)</h6>
      <b-pagination-nav :number-of-pages="10" base-url="#" v-model="currentPage" />
    </div>

    <div class="mt-3 text-center">
      <h6>Center alignment</h6>
      <b-pagination-nav align="center" :number-of-pages="10" base-url="#" v-model="currentPage" />
    </div>

    <div class="mt-3 text-right">
      <h6>Right (end) alignment</h6>
      <b-pagination-nav align="right" :number-of-pages="10" base-url="#" v-model="currentPage" />
    </div>

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

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

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

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.

Accessibility

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

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 "Go to first page"
label-prev-page "Go to previous page"
label-next-page "Go to next page"
label-last-page "Go to last page"
label-page "Go to page", appended with the page number
aria-label "Pagination", applied to the outer pagination container

Keyboard navigation support:

<b-pagination> supports keyboard navigation out of the box.

  • Tabbing into the pagination component will auto-focus the current page button
  • LEFT and RIGHT arrow keys will focus the previous and next buttons in the page list, respectively, and ENTER or SPACE keys will select (click) the focused page button

See also

For pagination control of a component (such as <b-table>), use the <b-pagination> component instead.

Pagination Nav Component Reference

<b-pagination-nav>

Properties

PropertyTypeDefault Value
disabledBooleanfalse
valueNumber or String1
limitNumber or String5
sizeStringmd
alignStringleft
hide-goto-end-buttonsBooleanfalse
aria-labelStringPagination
label-first-pageStringGo to first page
first-textString«
label-prev-pageStringGo to previous page
prev-textString
label-next-pageStringGo to next page
next-textString
label-last-pageStringGo to last page
last-textString»
label-pageStringGo to page
hide-ellipsisBooleanfalse
ellipsis-textString
number-of-pagesNumber or String1
base-urlString/
use-routerBooleanfalse
link-genFunction
page-genFunction
active-classString

Slots

SlotDescription
first-textThe "go to first page" button text (html/sub-components supported)
prev-textThe "go to previous page" button text (html/sub-components supported)
next-textThe "go to next page" button text (html/sub-components supported)
last-textThe "go to last page" button text (html/sub-components supported)
ellipsis-textThe '...' indicator text (html/sub-components supported)

Importing individual Pagination Nav Components

ComponentImport Path
<b-pagination-nav>bootstrap-vue/es/components/pagination-nav/pagination-nav

Example:

import BPaginationNav from 'bootstrap-vue/es/components/pagination-nav/pagination-nav'
Vue.component('b-pagination-nav', BPaginationNav)

Importing Pagination Nav as a Vue plugin

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

import { PaginationNav } from 'bootstrap-vue/es/components'
Vue.use(PaginationNav)