Pagination

For navigating across pages of related content.

styleKey: pagination

Passing page numbers via children is deprecated in SWAN v3.24

Always use the explicit pageNumber prop. The component uses this value to generate accessible announcements via SWAN's i18n system.

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 with an href to navigate between pages or update the URL (e.g., routing or query param changes). These components render as anchor (<a>) tags by default

ReactVanilla

<Pagination>
  <PaginationButton variant="previous" href="#" />
  <PaginationStep href="#" pageNumber={1} />
  <PaginationStep href="#" pageNumber={2} active />
  <PaginationEllipses />
  <PaginationStep href="#" pageNumber={27} />
  <PaginationStep href="#" pageNumber={28} />
  <PaginationButton variant="next" href="#" />
</Pagination>

<Pagination>
  <PaginationButton variant="previous" href="#" />
  <PaginationStep href="#" pageNumber={1} />
  <PaginationStep href="#" pageNumber={2} active />
  <PaginationEllipses />
  <PaginationStep href="#" pageNumber={27} />
  <PaginationStep href="#" pageNumber={28} />
  <PaginationButton variant="next" href="#" />
</Pagination>

<nav aria-label="Pagination" role="navigation" class="swan-pagination">
  <ul>
    <li>
      <span
        aria-label="Previous Page"
        href="#"
        role="button"
        class="swan-pagination-button-previous swan-pagination-button-disabled"
        ><img
          src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
          alt=""
          draggable="false"
          class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-type-chevronLeft"
          style='mask-image: url("{{ "chevronLeft" | icon }}");'
      /></span>
    </li>
    <li>
      <a
        aria-label="Page 1"
        href="#"
        aria-current="false"
        class="swan-pagination-step"
        >1</a
      >
    </li>
    <li>
      <a
        aria-label="Page 2"
        href="#"
        aria-current="true"
        class="swan-pagination-step swan-pagination-step-active"
        >2</a
      >
    </li>
    <li>
      <div aria-hidden="true" class="swan-pagination-step-ellipses"></div>
    </li>
    <li>
      <a
        aria-label="Page 27"
        href="#"
        aria-current="false"
        class="swan-pagination-step"
        >27</a
      >
    </li>
    <li>
      <span
        aria-label="Page 28"
        href="#"
        aria-current="false"
        class="swan-pagination-step"
        >28</span
      >
    </li>
    <li>
      <a
        aria-label="Next Page"
        href="#"
        role="button"
        class="swan-pagination-button-next"
        ><img
          src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
          alt=""
          draggable="false"
          class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-type-chevronRight"
          style='mask-image: url("{{ "chevronRight" | icon }}");'
      /></a>
    </li>
  </ul>
</nav>

<nav aria-label="Pagination" role="navigation" class="swan-pagination">
  <ul>
    <li>
      <span
        aria-label="Previous Page"
        href="#"
        role="button"
        class="swan-pagination-button-previous swan-pagination-button-disabled"
        ><img
          src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
          alt=""
          draggable="false"
          class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-type-chevronLeft"
          style='mask-image: url("{{ "chevronLeft" | icon }}");'
      /></span>
    </li>
    <li>
      <a
        aria-label="Page 1"
        href="#"
        aria-current="false"
        class="swan-pagination-step"
        >1</a
      >
    </li>
    <li>
      <a
        aria-label="Page 2"
        href="#"
        aria-current="true"
        class="swan-pagination-step swan-pagination-step-active"
        >2</a
      >
    </li>
    <li>
      <div aria-hidden="true" class="swan-pagination-step-ellipses"></div>
    </li>
    <li>
      <a
        aria-label="Page 27"
        href="#"
        aria-current="false"
        class="swan-pagination-step"
        >27</a
      >
    </li>
    <li>
      <span
        aria-label="Page 28"
        href="#"
        aria-current="false"
        class="swan-pagination-step"
        >28</span
      >
    </li>
    <li>
      <a
        aria-label="Next Page"
        href="#"
        role="button"
        class="swan-pagination-button-next"
        ><img
          src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
          alt=""
          draggable="false"
          class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-type-chevronRight"
          style='mask-image: url("{{ "chevronRight" | icon }}");'
      /></a>
    </li>
  </ul>
</nav>

When your pagination updates content dynamically within the same page, i.e., without a URL change or navigation, you should render each item as a <button> instead of an <a> tag.

To do this, omit the href prop and pass as="button" to each PaginationStep and PaginationButton.

ReactVanilla

<Pagination>
  <PaginationButton variant="previous" as="button" />
  <PaginationStep pageNumber={1} as="button" />
  <PaginationStep pageNumber={2} as="button" active />
  <PaginationEllipses />
  <PaginationStep pageNumber={27} as="button" />
  <PaginationStep pageNumber={28} as="button" />
  <PaginationButton variant="next" as="button" />
</Pagination>

<Pagination>
  <PaginationButton variant="previous" as="button" />
  <PaginationStep pageNumber={1} as="button" />
  <PaginationStep pageNumber={2} as="button" active />
  <PaginationEllipses />
  <PaginationStep pageNumber={27} as="button" />
  <PaginationStep pageNumber={28} as="button" />
  <PaginationButton variant="next" as="button" />
</Pagination>

<nav aria-label="Pagination" role="navigation" class="swan-pagination">
  <ul>
    <li>
      <button
        aria-label="Previous Page"
        disabled=""
        role="button"
        class="swan-pagination-button-previous swan-pagination-button-disabled"
      >
        <img
          src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
          alt=""
          draggable="false"
          class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-type-chevronLeft"
          style='mask-image: url("{{ "chevronLeft" | icon }}");'
        />
      </button>
    </li>
    <li>
      <button
        aria-label="Page 1"
        aria-current="false"
        class="swan-pagination-step"
      >
        1
      </button>
    </li>
    <li>
      <button
        aria-label="Page 2"
        aria-current="true"
        class="swan-pagination-step swan-pagination-step-active"
      >
        2
      </button>
    </li>
    <li>
      <div aria-hidden="true" class="swan-pagination-step-ellipses"></div>
    </li>
    <li>
      <button
        aria-label="Page 27"
        aria-current="false"
        class="swan-pagination-step"
      >
        27
      </button>
    </li>
    <li>
      <button
        aria-label="Page 28"
        disabled=""
        aria-current="false"
        class="swan-pagination-step swan-pagination-step-disabled"
      >
        28
      </button>
    </li>
    <li>
      <button
        aria-label="Next Page"
        role="button"
        class="swan-pagination-button-next"
      >
        <img
          src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
          alt=""
          draggable="false"
          class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-type-chevronRight"
          style='mask-image: url("{{ "chevronRight" | icon }}");'
        />
      </button>
    </li>
  </ul>
</nav>

<nav aria-label="Pagination" role="navigation" class="swan-pagination">
  <ul>
    <li>
      <button
        aria-label="Previous Page"
        disabled=""
        role="button"
        class="swan-pagination-button-previous swan-pagination-button-disabled"
      >
        <img
          src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
          alt=""
          draggable="false"
          class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-type-chevronLeft"
          style='mask-image: url("{{ "chevronLeft" | icon }}");'
        />
      </button>
    </li>
    <li>
      <button
        aria-label="Page 1"
        aria-current="false"
        class="swan-pagination-step"
      >
        1
      </button>
    </li>
    <li>
      <button
        aria-label="Page 2"
        aria-current="true"
        class="swan-pagination-step swan-pagination-step-active"
      >
        2
      </button>
    </li>
    <li>
      <div aria-hidden="true" class="swan-pagination-step-ellipses"></div>
    </li>
    <li>
      <button
        aria-label="Page 27"
        aria-current="false"
        class="swan-pagination-step"
      >
        27
      </button>
    </li>
    <li>
      <button
        aria-label="Page 28"
        disabled=""
        aria-current="false"
        class="swan-pagination-step swan-pagination-step-disabled"
      >
        28
      </button>
    </li>
    <li>
      <button
        aria-label="Next Page"
        role="button"
        class="swan-pagination-button-next"
      >
        <img
          src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
          alt=""
          draggable="false"
          class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-type-chevronRight"
          style='mask-image: url("{{ "chevronRight" | icon }}");'
        />
      </button>
    </li>
  </ul>
</nav>

Disabled

Use disabled onPaginationButton to indicate a boundary has been reached. Do not disable PaginationStep numbers.

ReactVanilla

<Pagination>
  <PaginationButton variant="previous" href="#" disabled />
  <PaginationStep href="#" pageNumber={1} active />
  <PaginationStep href="#" pageNumber={2} />
  <PaginationEllipses />
  <PaginationStep href="#" pageNumber={27} />
  <PaginationStep href="#" pageNumber={28} />
  <PaginationButton variant="next" href="#" />
</Pagination>

<Pagination>
  <PaginationButton variant="previous" href="#" disabled />
  <PaginationStep href="#" pageNumber={1} active />
  <PaginationStep href="#" pageNumber={2} />
  <PaginationEllipses />
  <PaginationStep href="#" pageNumber={27} />
  <PaginationStep href="#" pageNumber={28} />
  <PaginationButton variant="next" href="#" />
</Pagination>

<nav aria-label="Pagination" role="navigation" class="swan-pagination">
  <ul>
    <li>
      <span
        aria-label="Previous Page"
        href="#"
        role="button"
        class="swan-pagination-button-previous swan-pagination-button-disabled"
        ><img
          src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
          alt=""
          draggable="false"
          class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-type-chevronLeft"
          style='mask-image: url("{{ "chevronLeft" | icon }}");'
      /></span>
    </li>
    <li>
      <a
        aria-label="Page 1"
        href="#"
        aria-current="false"
        class="swan-pagination-step"
        >1</a
      >
    </li>
    <li>
      <a
        aria-label="Page 2"
        href="#"
        aria-current="true"
        class="swan-pagination-step swan-pagination-step-active"
        >2</a
      >
    </li>
    <li>
      <div aria-hidden="true" class="swan-pagination-step-ellipses"></div>
    </li>
    <li>
      <a
        aria-label="Page 27"
        href="#"
        aria-current="false"
        class="swan-pagination-step"
        >27</a
      >
    </li>
    <li>
      <span
        aria-label="Page 28"
        href="#"
        aria-current="false"
        class="swan-pagination-step swan-pagination-step-disabled"
        >28</span
      >
    </li>
    <li>
      <a
        aria-label="Next Page"
        href="#"
        role="button"
        class="swan-pagination-button-next"
        ><img
          src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
          alt=""
          draggable="false"
          class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-type-chevronRight"
          style='mask-image: url("{{ "chevronRight" | icon }}");'
      /></a>
    </li>
  </ul>
</nav>

<nav aria-label="Pagination" role="navigation" class="swan-pagination">
  <ul>
    <li>
      <span
        aria-label="Previous Page"
        href="#"
        role="button"
        class="swan-pagination-button-previous swan-pagination-button-disabled"
        ><img
          src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
          alt=""
          draggable="false"
          class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-type-chevronLeft"
          style='mask-image: url("{{ "chevronLeft" | icon }}");'
      /></span>
    </li>
    <li>
      <a
        aria-label="Page 1"
        href="#"
        aria-current="false"
        class="swan-pagination-step"
        >1</a
      >
    </li>
    <li>
      <a
        aria-label="Page 2"
        href="#"
        aria-current="true"
        class="swan-pagination-step swan-pagination-step-active"
        >2</a
      >
    </li>
    <li>
      <div aria-hidden="true" class="swan-pagination-step-ellipses"></div>
    </li>
    <li>
      <a
        aria-label="Page 27"
        href="#"
        aria-current="false"
        class="swan-pagination-step"
        >27</a
      >
    </li>
    <li>
      <span
        aria-label="Page 28"
        href="#"
        aria-current="false"
        class="swan-pagination-step swan-pagination-step-disabled"
        >28</span
      >
    </li>
    <li>
      <a
        aria-label="Next Page"
        href="#"
        role="button"
        class="swan-pagination-button-next"
        ><img
          src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
          alt=""
          draggable="false"
          class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-type-chevronRight"
          style='mask-image: url("{{ "chevronRight" | icon }}");'
      /></a>
    </li>
  </ul>
</nav>

disabled on PaginationStep is deprecated in SWAN v3.24

Individual pages should not be disabled, as doing so prevents users from accessing them and leaves them uncertain about the reason for their unavailability. Please remove uses of this prop.

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.
In the Vanilla API, the buttons need additional text to guide the user as to their function. Use aria-label and aria-describedby attributes (as show in the code examples above). Any aria-label values will need to be localized, since they will be presented to the user by screen readers and assistive devices.

Width

Use a consistent number of steps and ellipses in Pagination to maintain a uniform width.

Do

Dont

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

See core props for additional props that can be applied to each of these components. Each component also accepts the React-equivalent native HTML attributes of the element it renders, unless a listed prop replaces one or a note says otherwise.

Pagination

Renders <nav>.

prop	type	required	default	deprecation notes
⚠️ Deprecated `accessibleText` Provide the text that should be used for screen readers. @deprecated This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.	`stringnull`	false	null	This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.

PaginationButton

Renders <li>. Native HTML attributes and the ref go to its inner a (a button when disabled).

prop	type	required	default	deprecation notes
`disabled` Should it be disabled or not When true, always renders as a native `<button disabled>` regardless of the `as` prop.	`booleannull`	false	false
`variant` Button type	`"next""previous"null`	false	null
⚠️ Deprecated `accessibleText` Provide the text that should be used for screen readers. @deprecated This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.	`stringnull`	false	null	This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.

PaginationStep

Renders <li>. Native HTML attributes and the ref go to its inner a (a button when disabled).

prop	type	required	default	deprecation notes
`active` Should it be active or not	`booleannull`	false	false
⚠️ Deprecated `disabled` Should it be disabled or not When true, always renders as a native `<button disabled>` regardless of the `as` prop. @deprecated This is deprecated without a replacement. Individual pages should not be disabled.	`booleannull`	false	false	This is deprecated without a replacement. Individual pages should not be disabled.
⚠️ Deprecated `accessibleText` Provide the text that should be used for screen readers. @deprecated This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.	`stringnull`	false	null	This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support.
`pageNumber` The page number this step represents	`number`	false	null

Other components

These components have no props beyond core props and native HTML attributes.

Component	Renders	Notes
`PaginationEllipses`	`<li>`	Native HTML attributes and the ref go to its inner `div`.

Internationalization

SWAN's Internationalization System allows SWAN components to render with fully translated and accessible text out-of-the-box. The following keys are provided to allow you to override the default translation.

Default Text	Key
Pagination	`pagination.accessible-text`
Go to next page	`pagination-button-next.accessible-text-for-icon`
Go to previous page	`pagination-button-previous.accessible-text-for-icon`
Go to page {{pageNumber}}	`pagination-step.accessible-text-for-button`

Dropdown

Pagination

Use Pagination...

Don't use Pagination...

Pagination across pages

Pagination within a page (in-place updates)

Disabled

Implementation

Accessibility

Width

Do

Dont

Pagination with Dropdown

Props

Internationalization

Related