Pagination

Create accessible navigation controls for multi-page content with Chassis CSS's semantic pagination components.

Overview

Chassis CSS pagination provides intuitive navigation controls for multi-page content using semantic HTML structures and accessible design patterns. Built with list elements and proper ARIA attributes, pagination components ensure screen readers can effectively communicate navigation options while maintaining excellent keyboard accessibility.

Each pagination component uses connected page links with generous touch targets, making navigation reliable across all devices. The semantic <nav> wrapper identifies the component as a navigation section for assistive technologies, while descriptive labeling helps distinguish between multiple pagination contexts on the same page.

When implementing multiple pagination sections, provide descriptive aria-label attributes to clarify their purpose, such as aria-label="Search results pages" or aria-label="Blog post navigation".

html

<nav aria-label="Page navigation example">
  <ul class="pagination">
    <li class="page-item"><a class="page-link" href="#">Previous</a></li>
    <li class="page-item"><a class="page-link" href="#">1</a></li>
    <li class="page-item"><a class="page-link" href="#">2</a></li>
    <li class="page-item"><a class="page-link" href="#">3</a></li>
    <li class="page-item"><a class="page-link" href="#">Next</a></li>
  </ul>
</nav>

Working with icons

Transform pagination controls by replacing text with icons while maintaining comprehensive screen reader support through proper ARIA attributes and semantic markup.

html

<nav aria-label="Page navigation example">
  <ul class="pagination">
    <li class="page-item">
      <a class="page-link" href="#" aria-label="Previous">
        <span aria-hidden="true">&laquo;</span>
      </a>
    </li>
    <li class="page-item"><a class="page-link" href="#">1</a></li>
    <li class="page-item"><a class="page-link" href="#">2</a></li>
    <li class="page-item"><a class="page-link" href="#">3</a></li>
    <li class="page-item">
      <a class="page-link" href="#" aria-label="Next">
        <span aria-hidden="true">&raquo;</span>
      </a>
    </li>
  </ul>
</nav>

Active & disabled states

Clearly communicate current page position and unavailable navigation options using state classes and semantic attributes. Apply .disabled for non-interactive links and .active to highlight the current page.

In Chassis CSS, state classes can be applied to either the .page-item parent or directly to the .page-link element. While .disabled uses pointer-events: none to prevent mouse interaction, always include tabindex="-1" and aria-disabled="true" on disabled links to ensure complete keyboard accessibility.

html

<nav aria-label="...">
  <ul class="pagination">
    <li class="page-item disabled">
      <a class="page-link" tabindex="-1" aria-disabled="true">Previous</a>
    </li>
    <li class="page-item"><a class="page-link" href="#">1</a></li>
    <li class="page-item active" aria-current="page">
      <a class="page-link" href="#">2</a>
    </li>
    <li class="page-item"><a class="page-link" href="#">3</a></li>
    <li class="page-item">
      <a class="page-link" href="#">Next</a>
    </li>
  </ul>
</nav>

For enhanced accessibility and to completely remove click functionality, replace anchor elements with <span> for disabled and active states:

<li class="page-item disabled">
  <span class="page-link">Previous</span>
</li>

Sizing

Chassis provides three size variants to match your interface requirements. Add .large or .small modifiers to the base .pagination class for alternative sizing options.

html

<nav aria-label="...">
  <ul class="pagination large">
    <li class="page-item active" aria-current="page">
      <span class="page-link">1</span>
    </li>
    <li class="page-item"><a class="page-link" href="#">2</a></li>
    <li class="page-item"><a class="page-link" href="#">3</a></li>
  </ul>
</nav>

html

<nav aria-label="...">
  <ul class="pagination small">
    <li class="page-item active" aria-current="page">
      <span class="page-link">1</span>
    </li>
    <li class="page-item"><a class="page-link" href="#">2</a></li>
    <li class="page-item"><a class="page-link" href="#">3</a></li>
  </ul>
</nav>

Alignment

Control pagination positioning using Chassis's flexbox utilities. The pagination component uses flexbox by default, making it compatible with justify-content utilities for flexible alignment options.

With .justify-content-center:

html

<nav aria-label="Centered pagination">
  <ul class="pagination justify-content-center">
    <li class="page-item disabled">
      <a class="page-link" tabindex="-1" aria-disabled="true">Previous</a>
    </li>
    <li class="page-item"><a class="page-link" href="#">1</a></li>
    <li class="page-item"><a class="page-link" href="#">2</a></li>
    <li class="page-item"><a class="page-link" href="#">3</a></li>
    <li class="page-item">
      <a class="page-link" href="#">Next</a>
    </li>
  </ul>
</nav>

Or with .justify-content-end:

html

<nav aria-label="Right-aligned pagination">
  <ul class="pagination justify-content-end">
    <li class="page-item disabled">
      <a class="page-link" tabindex="-1" aria-disabled="true">Previous</a>
    </li>
    <li class="page-item"><a class="page-link" href="#">1</a></li>
    <li class="page-item"><a class="page-link" href="#">2</a></li>
    <li class="page-item"><a class="page-link" href="#">3</a></li>
    <li class="page-item">
      <a class="page-link" href="#">Next</a>
    </li>
  </ul>
</nav>

CSS

This component can be customized using CSS variables, allowing for styles to be modified dynamically on the page. These CSS variables are part of Chassis CSS's design token system, giving design teams control over component appearance. See the design tokens page for more details.

Custom properties

These CSS variables control the component's appearance and can be modified dynamically on the page. Components use cascading variables, allowing seamless variations in size, color, and style without redundant style declarations through component inheritance and the context class system.

scss/_pagination.scss

--#{$prefix}padding-y: var(--#{$prefix}pagination-padding-y, #{$pagination-padding-y});
--#{$prefix}padding-x: var(--#{$prefix}pagination-padding-x, #{$pagination-padding-x});
--#{$prefix}fg-color: var(--#{$prefix}pagination-fg-color, #{$pagination-fg-color});
--#{$prefix}bg-color: var(--#{$prefix}pagination-bg-color, #{$pagination-bg-color});
--#{$prefix}border-width: var(--#{$prefix}pagination-border-width, #{$pagination-border-width});
--#{$prefix}border-color: var(--#{$prefix}pagination-border-color, #{$pagination-border-color});
--#{$prefix}border-radius: var(--#{$prefix}pagination-border-color, #{$pagination-border-radius});
--#{$prefix}icon-color: var(--#{$prefix}pagination-icon-color, var(--#{$prefix}fg-color));
--#{$prefix}icon-size: var(--#{$prefix}pagination-icon-size, var(--#{$prefix}icon-small));
@include map-font($pagination-font, pagination);

Sass variables

These Sass variables are also exposed as CSS custom properties using the --cx- prefix. A Sass variable $variable-name becomes available as --cx-variable-name in CSS, allowing for styles to be modified dynamically on the page. See the context components page for more details.

scss/_variables.scss

$pagination-padding-y:                  $button-medium-padding-y;
$pagination-padding-x:                  $button-medium-padding-x;
$pagination-border-radius:              $button-medium-border-radius;
$pagination-font:                       $cx-font-text-medium-normal;

$pagination-large-padding-y:            $button-large-padding-y;
$pagination-large-padding-x:            $button-large-padding-x;
$pagination-large-border-radius:        $button-large-border-radius;
$pagination-large-font:                 $cx-font-text-large-normal;

$pagination-small-padding-y:            $button-small-padding-y;
$pagination-small-padding-x:            $button-small-padding-x;
$pagination-small-border-radius:        $button-small-border-radius;
$pagination-small-font:                 $cx-font-text-small-normal;

$pagination-border-width:               $border-width-medium;
$pagination-margin-start:               calc(#{$pagination-border-width} * -1); // stylelint-disable-line function-disallowed-list
$pagination-border-color:               var(--#{$prefix}border-main);

$pagination-fg-color:                   var(--#{$prefix}fg-main);
$pagination-bg-color:                   var(--#{$prefix}bg-main);

$pagination-focus-fg-color:             var(--#{$prefix}fg-main);
$pagination-focus-bg-color:             var(--#{$prefix}bg-main);
$pagination-focus-box-shadow:           $focus-ring-box-shadow;
$pagination-focus-outline:              0;

$pagination-hover-fg-color:             var(--#{$prefix}fg-hover);
$pagination-hover-bg-color:             var(--#{$prefix}bg-hover);

$pagination-active-fg-color:            $component-active-fg-color;
$pagination-active-bg-color:            $component-active-bg-color;
$pagination-active-border-color:        $component-active-bg-color;

$pagination-disabled-fg-color:          var(--#{$prefix}fg-slight);
$pagination-disabled-bg-color:          var(--#{$prefix}bg-main);
$pagination-disabled-border-color:      $pagination-border-color;

$pagination-transition:                 color .15s ease-in-out, background-color .15s ease-in-out, border-color .15s ease-in-out, box-shadow .15s ease-in-out;