Pagination

For navigating across pages of related content.

styleKeys: pagination

UsageGuidelinesAPI

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.

Use PaginationButton and PaginationStep to enable navigation across pages.

ReactVanilla

<Pagination accessibleText="Pagination">
  <PaginationButton
    variant="previous"
    href="#"
    accessibleText="Previous Page"
    disabled
  />
  <PaginationStep href="#" accessibleText="Page 1">
    1
  </PaginationStep>
  <PaginationStep href="#" active accessibleText="Page 2">
    2
  </PaginationStep>
  <PaginationEllipses />
  <PaginationStep href="#" accessibleText="Page 27">
    27
  </PaginationStep>
  <PaginationStep href="#" disabled accessibleText="Page 28">
    28
  </PaginationStep>
  <PaginationButton variant="next" href="#" accessibleText="Next Page" />
</Pagination>

<Pagination accessibleText="Pagination">
  <PaginationButton
    variant="previous"
    href="#"
    accessibleText="Previous Page"
    disabled
  />
  <PaginationStep href="#" accessibleText="Page 1">
    1
  </PaginationStep>
  <PaginationStep href="#" active accessibleText="Page 2">
    2
  </PaginationStep>
  <PaginationEllipses />
  <PaginationStep href="#" accessibleText="Page 27">
    27
  </PaginationStep>
  <PaginationStep href="#" disabled accessibleText="Page 28">
    28
  </PaginationStep>
  <PaginationButton variant="next" href="#" accessibleText="Next Page" />
</Pagination>

<nav aria-label="Pagination" role="navigation" class="swan-pagination">
  <span
    aria-label="Previous Page"
    href="#"
    role="button"
    class="swan-pagination-button-previous swan-pagination-button-disabled"
    ><img
      role="presentation"
      src="https://swan.prod.merch.vpsvc.com/v0/icons/arrow_l.e20e6f3e96185b4d6639de046b03417e.svg"
      class="swan-icon swan-icon-skin-standard swan-icon-type-arrowL" /></span
  ><a aria-label="Page 1" aria-current="false" class="swan-pagination-step">1</a
  ><a
    aria-label="Page 2"
    aria-current="true"
    class="swan-pagination-step swan-pagination-step-active"
    >2</a
  >
  <div class="swan-pagination-step-ellipses"></div>
  <a aria-label="Page 27" aria-current="false" class="swan-pagination-step"
    >27</a
  ><span
    aria-label="Page 28"
    aria-current="false"
    class="swan-pagination-step swan-pagination-step-disabled"
    >28</span
  ><a
    aria-label="Next Page"
    href="#"
    role="button"
    class="swan-pagination-button-next"
    ><img
      role="presentation"
      src="https://swan.prod.merch.vpsvc.com/v0/icons/arrow_r.6f9e50e48b6db640d421ebc9c7177f3c.svg"
      class="swan-icon swan-icon-skin-standard swan-icon-type-arrowR"
  /></a>
</nav>

<nav aria-label="Pagination" role="navigation" class="swan-pagination">
  <span
    aria-label="Previous Page"
    href="#"
    role="button"
    class="swan-pagination-button-previous swan-pagination-button-disabled"
    ><img
      role="presentation"
      src="https://swan.prod.merch.vpsvc.com/v0/icons/arrow_l.e20e6f3e96185b4d6639de046b03417e.svg"
      class="swan-icon swan-icon-skin-standard swan-icon-type-arrowL" /></span
  ><a aria-label="Page 1" aria-current="false" class="swan-pagination-step">1</a
  ><a
    aria-label="Page 2"
    aria-current="true"
    class="swan-pagination-step swan-pagination-step-active"
    >2</a
  >
  <div class="swan-pagination-step-ellipses"></div>
  <a aria-label="Page 27" aria-current="false" class="swan-pagination-step"
    >27</a
  ><span
    aria-label="Page 28"
    aria-current="false"
    class="swan-pagination-step swan-pagination-step-disabled"
    >28</span
  ><a
    aria-label="Next Page"
    href="#"
    role="button"
    class="swan-pagination-button-next"
    ><img
      role="presentation"
      src="https://swan.prod.merch.vpsvc.com/v0/icons/arrow_r.6f9e50e48b6db640d421ebc9c7177f3c.svg"
      class="swan-icon swan-icon-skin-standard swan-icon-type-arrowR"
  /></a>
</nav>

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.

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.