vue-sliding-pagination

# Guide

# Usage

Basic usage of the pagination component only requires the current page, the total number of pages and a handler which is called on page change.

The pagination component does not handle page changes by itself, instead you are required to provide a page change handler which should contain all your page changing logic (e.g. a vuex store dispatch) and eventually change the current page to the passed one. In later releases, a v-model approach to currentPage may be offered, but was opted against for the time being.

Thus, to get a paginator with default settings (please consult the options listing below for details), the following markup and script sections provide a starting point:

<sliding-pagination
  :current="currentPage"
  :total="totalPages"
  @page-change="pageChangeHandler"
></sliding-pagination>

import SlidingPagination from 'vue-sliding-pagination'

// in component or vue instance
components: {
  // ...
  SlidingPagination
},
data() {
  return {
    // ...
    currentPage: 1,
    totalPages: 10
  }
},
methods: {
  // ...
  pageChangeHandler(selectedPage) {
    this.currentPage = selectedPage
  }
}

Additionally, the CSS for the component should be made available. Please refer to the Styles customization section below

# Options

name type default description
ariaPaginationLabel String 'Pagination navigation' ARIA label for the whole <nav> area
ariaGotoPageLabel String 'Go to page %page% of %total%' ARIA label for a page link that is not the current page
ariaPreviousPageLabel String 'Go to previous page' ARIA label for the previous page action
ariaNextPageLabel String 'Go to next page' ARIA label for the next page action
ariaCurrentPageLabel String 'Page %current of %total, current page' ARIA label for the current page
classMap Object default class map CSS classes used by the components
current Number - Integer representing the current page
total Number - Integer representing the total number of pages
slidingEndingSize Number 2 Number of always listed pages on the beginning and end
slidingWindowSize Number 3 Number of pages in the sliding window
nonSlidingSize Number 9 Number of pages before the paginator switches to sliding mode
pageComponent String 'sliding-pagination-default-page' Component name (must be registered) for the page elements

# Customization

The component offers severals customization options.

# ARIA labels

All ARIA labels can be altered and localized.

The labels ariaGoToPageLabel and ariaCurrentPageLabel support the following template variables:

Variable Type Description
%total% Number The total number of pages
%page% Number The page under the cursor

# Intervals

The number of pages shown on the beginning and ending of the pager as well as the number of pages in the pagination window can be changed dynamically. The break-point from normal to sliding-window pagination can also be adjusted. Please bear in mind that none of these intervals and none of the calculations they are used in make any assertions on obviously impossible configurations!

What are obviously impossible configurations?

Glad you're asking! For one, the rule of thumb should be 2 * slidingEndingSize + slidingWindowSize <= total. However, as there is a fallback coated as nonSlidingSize you can work around this "limitation" with some ingenouity on your part. Basically, don't do stupid things that disregards principles of natural numbers.

# Page navigation

The content of the previous and next page elements are customizable via the slots previous-page and next-page. By default, these only contain the "pretend arrows" aka « and ». The contents of these slots are only intended for visual use. Screenreader users are presented the ariaPreviousPageLabel and ariaNextPageLabel instead.

# Gaps

Depending on the current page, there may be a gap between the sliding window and the beginning and ending pages. The gap content defaults to … but can be customized for visual use under the same conditions as the page navigation with the slots gap-left and gap-right.

# Page component

Since actual pages are the most active element of the whole pagination deal, they have been implemented with the <component :is="paginationComponent"> pattern.

The SlidingPaginationDefaultPage component offers guidance into how a basic component representing page elements should look like. It's unit test can be used as a basis for unit testing custom page components.

The page component receives the following props:

name type description
ariaPageLabel String The computed ARIA page label
isCurrent Boolean Is the page the current page
page Number The page number to display

It is by no means required to implement all properties of the default page. A custom pagination component can usually just be implemented as render function, e.g.

Vue.component('ExamplePageComponent', {
  props: {
    page: {
      type: Number,
      required: true
    }
  },

  render (h) {
    return h('a', { class: 'page-component' }, this.page)
  }
})

<sliding-pagination
  ...
  pagination-component="example-page-component"
></sliding-pagination>

Please keep in mind that the above example is absurdly simple for demonstration purposes and breaks the ARIA compatibility of the whole pagination component.

# Styling

The CSS classes used in the component are following the BEM (opens new window)-Methodology, regarding only the component itself as a block and going downward from there, thus the corresponding classes to interface elements are:

Class Interface element
.c-sliding-pagination The whole component i.e. the <nav> container
.c-sliding-pagination__list The <ul> containing all navigational and page elements
.c-sliding-pagination__list-element Each <li> representing either a navigational or a page element
.c-sliding-pagination__list-element--active The <li> representing the current page
.c-sliding-pagination__list-element--disabled Disabled navigational elements
.c-sliding-pagination__page The page element inside an <li> (typically an <a>)

To get the default styling, you may either add dist/style/vue-sliding-pagination.css as a CSS asset to your page:

@import "~vue-sliding-pagination/dist/style/vue-sliding-pagination.css";

For ease of customization, the original SCSS styling files are available in the distribution package in the dist/style subdir, allowing quick and deep customization by utilizing the exposed variables and re-declaring classes:

$sliding-pagination-background-primary: $background-primary;
$sliding-pagination-background-secondary: $background-secondary;
$sliding-pagination-foreground-primary: $color-foreground-primary;
$sliding-pagination-foreground-secondary: $color-foreground-secondary;

@import "~vue-sliding-pagination/dist/style/sliding-pagination";

.c-sliding-pagination {
  text-align: center;
  margin: 1.5em 0;
}

# Class Map

If you need to adjust the class names inside the component, you can pass an object to reconfigure the classMap used to determine any CSS class inside the component.

Here are the defaults:

{
  "componentClass": "c-sliding-pagination",
  "list": "c-sliding-pagination__list",
  "element": "c-sliding-pagination__list-element",
  "elementDisabled": "c-sliding-pagination__list-element--disabled",
  "elementActive": "c-sliding-pagination__list-element--active",
  "page": "c-sliding-pagination__page"
}

Examples →