Allows users to navigate to next or previous page when content is split into several pages
At the sm, md, and lg breakpoints, pagination displays as a list of number text links. Prev and Next links are also added when applicable.
The scoped slots can be used to override the default links rendered in the pagination. Useful for integrating with client-side routing, as a router-link
can be rendered instead of a plain a
tag. Pagination exposes 3 link scopedSlots: link
, prevLink
, and nextLink
.
The 'link' slot scope exposes the following prop object:
attrs: {
class,
'aria-label',
'aria-current',
ref:,
},
href,
page,
content,
click,
class
: a class to be applied to the link in order to match pagination stylingaria-label
: default aria-label for this linkaria-current
: reflects whether current link is the currently selected pageref
: vue ref for tracking the element. Required for internal component behaviorhref
: href that the link points to by defaultpage
: the page number that corresponds to this link. NOTE: that you must manually update your v-model attribute to be the value of page
whenever this link is clickedcontent
: the default content for that linkclick
: function ran when element is clicked. Required for internal component behaviorThe prevLink
and nextLink
slot scopes expose the following prop object:
attrs: {
class,
'aria-label',
ref,
},
href,
page,
content,
iconClass,
iconComponent,
iconPath,
click,
class
: a class to be applied to the link in order to match pagination stylingaria-label
: default aria-label for this linkref
: vue ref for tracking the element for internal component behaviorhref
: href that the link points to by defaultpage
: the page number that corresponds to this link. NOTE: that you must manually update your v-model attribute to be the value of page
whenever this link is clickedcontent
: the default content for that linkiconClass
: a class to be applied to the prev/next arrow icon in order to match pagination stylingiconPath
: the path to the icon in the Cedar Icon Library (opens new window) used for this linkiconComponent
: name of the component used for this linkclick
: function ran when element is clicked. Required for internal component behaviorAt the xs breakpoint, pagination adapts to a Select component using the native UI dropdown menu.
This component complies with accessibility guidelines by doing the following:
<nav>
element to let screen readers recognize the pagination controlsaria-label="pagination"
to describe the type of navigationaria-current="page"
to the link that points to the current pageView the videos at a11ymattters, Accessible Pagination (opens new window) for a demonstration of before and after pagination tests using a screen reader voiceover.
This component has compliance WCAG guidelines by:
Within pagination, link styles are adapted
By default, pagination is center aligned under category or search results content.
The primary placement for pagination is at the bottom of a page that displays rows of content.
Use pagination logic to truncate link list, when possible.
Pagination adapts to a Select component with a native UI dropdown menu on XS breakpoints to provide a mobile-friendly experience.
pages
name
array
type
N/A
default
Array of objects containing pagination data. Objects have structure of { page: number, url: string }. Required.
totalPages
name
number
type
null
default
Sets the total number of pages for displaying "Page x of <totalPages>". Sometimes the total number of pages is different than total page data objects in the pages array. For example, if only the next and previous pages are provided.
input
name
pageNumber, event
arguments
$emit event fired when page prop value is updated.
navigate
name
pageNumber, url, event
arguments
$emit event fired when page changes based on user interaction by clicking a link or selecting an option from the select on mobile.
Find more information about using Slots in the article Getting Started as a Developer.
link
name
Scoped slot used to override the default page links used. Useful for integrating with client-side routing. See "Scoped Slots and vue-router" below for exposed prop API.
prevLink
name
Scoped slot used to override the default previous page link. Useful for integrating with client-side routing. See "Scoped Slots and vue-router" below for exposed prop API.
nextLink
name
Scoped slot used to override the default next page link. Useful for integrating with client-side routing. See "Scoped Slots and vue-router" below for exposed prop API.
The CdrPagination component provides a current page number control and renders a list of links. The current page value should be bound using v-model
in your app.
The CdrPagination component does not make data calls, render or track paginated data, or handle routing beyond simple anchor links. However, it does emit events if you need to customize routing or need to add additional application logic.
Previous, next, and individual page links can have their template overridden via scoped slots. While this isn't advisable under normal circumstances, it is necessary to make the component work with vue-router. It is similar to the scoped slot example but uses router-link
with no click event (when paired with a computed prop v-model):
<cdr-pagination
:pages="pages"
:total-pages="20"
v-model="page"
>
<!-- Previous -->
<template v-slot:prevLink="prevLink">
<router-link
v-bind="prevLink.attrs"
:to="{ query: { 'page': prevLink.page } }"
replace
>
<component
:is="prevLink.iconComponent"
:class="prevLink.iconClass"
/>
{{ prevLink.content }}
</router-link>
</template>
<!-- Single Page links -->
<template v-slot:link="link">
<router-link
v-bind="link.attrs"
:to="{ query: { 'page': link.page } }"
replace
>
{{ link.page }}
</router-link>
</template>
<!-- Next -->
<template v-slot:nextLink="nextLink">
<router-link
v-bind="nextLink.attrs"
:to="{ query: { 'page': nextLink.page } }"
replace
>
{{ nextLink.content }}
<component
:is="nextLink.iconComponent"
:class="nextLink.iconClass"
/>
</router-link>
</template>
</cdr-pagination>
...
<script>
...
computed: {
page: {
get() {
return parseInt(this.$route.query['page'], 10) || 1;
},
set() {
// No need to do anything for the component here
},
},
},
</script>
For best SEO support, use of pagination requires additional markup and logic in the <head>
of the page.
See REI's SEO Confluence page on pagination (opens new window) for information on implementing this correctly on your page.
Note that REI has chosen HTML <link>
elements instead of HTTP headers. Make sure to use fully qualified absolute URLs in the <link>
elements instead of relative URLs.