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>
Attribute | Type | Description |
---|---|---|
count (required) | integer | Total number of items being paginated |
display (required) | integer | Number of items displayed per page |
page | integer | Set display page |
ticks | integer | Number of available page slots in default pagination (defaults to 10, cannot be less than 7) |
pagination | string | Set alternative pagination type
|
navigation | string | Set navigation display type
|
indicator | string | Set indicator display
|
disabled | boolean | Set initial state to disabled |
API
Name | Type | Data | Description |
---|---|---|---|
page | property | integer | Get/set current page |
count | property | integer | Get/set paginated item total |
display | property | integer | Get/set number of items displayed per page |
ticks | property | integer | Get/set number of ticks displayed in pagination |
pagination | property | string | Get/set pagination type (pass false to reset to default) |
navigation | property | string | Get/set navigation type |
indicator | property | string | Get/set indicator type (pass false to remove) |
Events
Event | Detail | Returns |
---|---|---|
change | detail.page | Requested page |
Notes
Depends on:History
Version | Note |
---|---|
0.21.4 | Package upgrades cause CSS build to remove -moz-user-select and -ms-user-select properties |
0.15.0 | Add comma separators to page numbers greater than 999. |
0.13.0 | Make previous/next indicators remain visible and prevent page from changing when component is disabled. |
0.12.0 | Apply new spacing scale. |
0.11.4 | Add optional disabled property |
0.11.3 | Add conditional for inital build of pagination based on count and display props. |
0.11.0 | Update event from pagination:change to change . Tweaks to accommodate new icon set. |
0.10.0 | Color update |
0.7.0 | Initial build to spec. |