<iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5HGSQD2L" height="0" width="0" style="display:none;visibility:hidden" title="GTM"></iframe>

Pagination

For navigating across pages of related content.
styleKeys: pagination

Use Pagination...

  • For navigation across a range of pages of related content.
  • To indicate a user's position within that range.

Don't use Pagination...

  • For navigation within a small set of elements, where simple scrolling can suffice.

Pagination allows for navigation across a range of pages of related content, and also indicates a user's position within that range. SWAN provides a standard set of controls, leaving it up to the particular page to implement the pagination logic behind them.

Pagination with buttons

Use PaginationButton and PaginationStep to enable navigation across pages.

The preview has been updated.

Implementation

  • Pagination is a simple set of controls with no actual pagination logic behind them. The page that uses it will need to:
    • attach the URLs and/or handle any clicks to the Previous and Next buttons
    • attach a change handler to the input field, taking the user to the specified page when the input's value is changed
  • Pagination buttons can use either <a> or <button> tags. The React PaginationButton component will default to <a> tags. Use <a> tags if a click takes the user to a new page; use <button> tags if a click loads new content into the same page.
  • If the user is on the first or last page, the Previous or Next button should be disabled accordingly:
    • In the React API: add the disabled prop to the PaginationButton.
    • In the Vanilla API: if your Pagination use <a> tags, change the Prev/Next button to a <span> tag and add class swan-pagination-button-disabled. If your Pagination uses <button> tags, disable the button as you normally would for a button, by adding the attribute disabled="disabled".

Accessibility

  • The "buttons" in Pagination default to <a> tags, which means they are links and need an href attribute. If your Pagination buttons aren't links, and instead perform in-page actions, they should be <button> tags, such as by using as="button" in the React API.
  • The buttons need additional text to guide the user as to their function.
    • In the React API, use the accessibleText prop to provide guidance (as shown in the code example above).
    • In the Vanilla API, use aria-label and aria-describedby attributes (as show in the code example above). Any aria-label values will need to be localized, since they will be presented to the user by screen readers and assistive devices.

Pagination with Dropdown

  • Integrating a Dropdown with Pagination enables users to control their viewing experience by selecting how many items they wish to see per page.
  • Link the Dropdown and Pagination controls so that changes in one affect the other. For example, if a user selects a new number of items per page, ensure the Pagination updates accordingly.

Props

Pagination
This component is implemented using the <nav /> as the root element. You can utilize the native attributes supported by <nav /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
proptyperequireddescriptiondefault
accessibleTextstring | nullfalse
Provide the text that should be used for screen readers.
null
PaginationButton
This component is implemented using the <a /> as the root element. You can utilize the native attributes supported by <a /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
proptyperequireddescriptiondefault
disabledboolean | nullfalse
Should it be disabled or not
null
accessibleTextstring | nullfalse
Provide the text that should be used for screen readers.
null
variant"next" | "previous" | nullfalse
Button type
null
PaginationEllipses
This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
PaginationLabel
This component is implemented using the <span /> as the root element. You can utilize the native attributes supported by <span /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
PaginationStep
This component is implemented using the <a /> as the root element. You can utilize the native attributes supported by <a /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
proptyperequireddescriptiondefault
disabledboolean | nullfalse
Should it be disabled or not
null
accessibleTextstring | nullfalse
Provide the text that should be used for screen readers.
null
activeboolean | nullfalse
Should it be active or not
null

Related

Was this page useful?

Thanks for your feedback!

Feel free to include your name if you wish to have a follow up conversation.


Published: Jan 7, 2022Last updated: Sep 18, 2024