Pagination A navigational component to move through multiple related screens.

When a series of results or records are displayed in groups across multiple screens, pagination is used to indicate the breadth of results and screens. Pagination includes forward and back buttons that allow people to move across screens, and clickable numerical buttons that help people to move to a specific position in the results.

Table of contents


Usage guidelines

When to use
  • Pagination is especially useful for contexts where there are many pieces of data to scroll through, such as search results.
How to use
  • Depending on the size taken up by each record, default to displaying somewhere between 25 and 75 results per page.
  • When results are denser, more difficult to scan, or will take longer to load, include fewer results.
  • When results are easier or faster to scan, include more results.
  • Numbered pagination can be difficult to use at small widths because of their horizontal format and small tap target size. When designing for contexts with smaller widths, such as drawers, consider using nav-only pagination.

Variations

Pagination
Page numbers (default)

The default pagination only includes page numbers. This pattern may be used when there is a smaller set of results with a known size—usually broken across less than 15 pages—and it is easy to navigate to the end of the set.

Page numbers and indicator

Use the indicator as well as page numbers when there is a larger or variable set of results and more wayfinding tools will help to navigate the data.

Text only

This is the most basic form of the pagination in that it only uses the “prev/next” buttons.

This pattern is designed to accommodate very large sets of records in which people are unlikely to find what they’re looking for by page number. In these use cases, people will typically rely on searching and filtering to narrow down results, and use prev/next button to scroll across paginated search results.

Nav only

This pagination pattern is optimized for small screens, drawers, and small breakpoints. Use this pattern by default in contexts without much horizontal space.


Attributes

An asterisk next to a value denotes that it is the default value for that attribute. Unless noted otherwise, attributes should be added to the component element directly. Boolean attributes work based on their presence or absence from the component.

<res-component booleanAttribute stringAttribute="parameter">    
  <child-element></child-element>
</res-component>
AttributeTypeDescription
count (required)integerTotal number of items being paginated
display (required)integerNumber of items displayed per page
pageintegerSet display page
ticksintegerNumber of available page slots in default pagination (defaults to 10, cannot be less than 7)
paginationstringSet alternative pagination type
  • text-only
  • nav-only
  • nav-only-toggle
navigationstringSet navigation display type
  • text
indicatorstringSet indicator display
  • page
  • range
  • both
disabledbooleanSet initial state to disabled

API

NameTypeDataDescription
pagepropertyintegerGet/set current page
countpropertyintegerGet/set paginated item total
displaypropertyintegerGet/set number of items displayed per page
tickspropertyintegerGet/set number of ticks displayed in pagination
paginationpropertystringGet/set pagination type (pass false to reset to default)
navigationpropertystringGet/set navigation type
indicatorpropertystringGet/set indicator type (pass false to remove)

Events

EventDetailReturns
changedetail.pageRequested page

Notes

Depends on:

History

VersionNote
0.21.4Package upgrades cause CSS build to remove -moz-user-select and -ms-user-select properties
0.15.0Add comma separators to page numbers greater than 999.
0.13.0Make previous/next indicators remain visible and prevent page from changing when component is disabled.
0.12.0Apply new spacing scale.
0.11.4Add optional disabled property
0.11.3Add conditional for inital build of pagination based on count and display props.
0.11.0Update event from pagination:change to change. Tweaks to accommodate new icon set.
0.10.0Color update
0.7.0Initial build to spec.