Pagination

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

@layer components

Component tokens

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".

<nav aria-label="Page navigation example">
  <ul class="pagination">
    <li class="pagination-item">
      <a class="pagination-link" href="#" aria-label="Previous">
        <svg class="icon directional-icon" aria-hidden="true"><use href="#chevron-left-solid"></use></svg>
      </a>
    </li>
    <li class="pagination-item"><a class="pagination-link" href="#">1</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">2</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">3</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">4</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">5</a></li>
    <li class="pagination-item">
      <a class="pagination-link" href="#" aria-label="Next">
        <svg class="icon directional-icon" aria-hidden="true"><use href="#chevron-right-solid"></use></svg>
      </a>
    </li>
  </ul>
</nav>

Bordered

Add .bordered to the .pagination class to create a distinct separation between page links, enhancing visual clarity and touch target definition.

<nav aria-label="Page navigation example">
  <ul class="pagination bordered">
    <li class="pagination-item">
      <a class="pagination-link" href="#" aria-label="Previous">
        <svg class="icon directional-icon" aria-hidden="true"><use href="#chevron-left-solid"></use></svg>
      </a>
    </li>
    <li class="pagination-item"><a class="pagination-link" href="#">1</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">2</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">3</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">4</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">5</a></li>
    <li class="pagination-item">
      <a class="pagination-link" href="#" aria-label="Next">
        <svg class="icon directional-icon" aria-hidden="true"><use href="#chevron-right-solid"></use></svg>
      </a>
    </li>
  </ul>
</nav>

Grouped

Use .grouped to create a connected pagination layout where page links appear as a single unit, emphasizing their relationship and improving usability.

<nav aria-label="Page navigation example">
  <ul class="pagination grouped">
    <li class="pagination-item">
      <a class="pagination-link" href="#" aria-label="Previous">
        <svg class="icon directional-icon" aria-hidden="true"><use href="#chevron-left-solid"></use></svg>
      </a>
    </li>
    <li class="pagination-item"><a class="pagination-link" href="#">1</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">2</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">3</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">4</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">5</a></li>
    <li class="pagination-item">
      <a class="pagination-link" href="#" aria-label="Next">
        <svg class="icon directional-icon" aria-hidden="true"><use href="#chevron-right-solid"></use></svg>
      </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 .pagination-item parent or directly to the .pagination-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.

<nav aria-label="...">
  <ul class="pagination">
    <li class="pagination-item disabled">
      <span class="pagination-link">
        <svg class="icon directional-icon" aria-hidden="true"><use href="#chevron-left-solid"></use></svg>
      </span>
    </li>
    <li class="pagination-item active"><a class="pagination-link" href="#">1</a></li>
    <li class="pagination-item" aria-current="page">
      <a class="pagination-link" href="#">2</a>
    </li>
    <li class="pagination-item"><a class="pagination-link" href="#">3</a></li>
    <li class="pagination-item">
      <a class="pagination-link" href="#" aria-label="Next">
        <svg class="icon directional-icon" aria-hidden="true"><use href="#chevron-right-solid"></use></svg>
      </a>
    </li>
  </ul>
</nav>

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

Sizing

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

<nav aria-label="...">
  <ul class="pagination lg">
    <li class="pagination-item">
      <a class="pagination-link" href="#" aria-label="Previous">
        <svg class="icon directional-icon" aria-hidden="true"><use href="#chevron-left-solid"></use></svg>
      </a>
    </li>
    <li class="pagination-item"><a class="pagination-link" href="#">1</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">2</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">3</a></li>
    <li class="pagination-item">
      <a class="pagination-link" href="#" aria-label="Next">
        <svg class="icon directional-icon" aria-hidden="true"><use href="#chevron-right-solid"></use></svg>
      </a>
    </li>
  </ul>
</nav>

<nav aria-label="...">
  <ul class="pagination sm">
    <li class="pagination-item">
      <a class="pagination-link" href="#" aria-label="Previous">
        <svg class="icon directional-icon" aria-hidden="true"><use href="#chevron-left-solid"></use></svg>
      </a>
    </li>
    <li class="pagination-item"><a class="pagination-link" href="#">1</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">2</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">3</a></li>
    <li class="pagination-item">
      <a class="pagination-link" href="#" aria-label="Next">
        <svg class="icon directional-icon" aria-hidden="true"><use href="#chevron-right-solid"></use></svg>
      </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:

<nav aria-label="Centered pagination">
  <ul class="pagination justify-content-center">
    <li class="pagination-item">
      <a class="pagination-link" href="#" aria-label="Previous">
        <svg class="icon directional-icon" aria-hidden="true"><use href="#chevron-left-solid"></use></svg>
      </a>
    </li>
    <li class="pagination-item"><a class="pagination-link" href="#">1</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">2</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">3</a></li>
    <li class="pagination-item">
      <a class="pagination-link" href="#" aria-label="Next">
        <svg class="icon directional-icon" aria-hidden="true"><use href="#chevron-right-solid"></use></svg>
      </a>
    </li>
  </ul>
</nav>

Or with .justify-content-end:

<nav aria-label="Right-aligned pagination">
  <ul class="pagination justify-content-end">
    <li class="pagination-item">
      <a class="pagination-link" href="#" aria-label="Previous">
        <svg class="icon directional-icon" aria-hidden="true"><use href="#chevron-left-solid"></use></svg>
      </a>
    </li>
    <li class="pagination-item"><a class="pagination-link" href="#">1</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">2</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#">3</a></li>
    <li class="pagination-item">
      <a class="pagination-link" href="#" aria-label="Next">
        <svg class="icon directional-icon" aria-hidden="true"><use href="#chevron-right-solid"></use></svg>
      </a>
    </li>
  </ul>
</nav>

CSS

This component can be customized through Sass variables at compile time.

Custom properties

This component exposes CSS custom properties to control its appearance at runtime.

--cx-padding-y: var(--cx-pagination-padding-y, var(--cx-space-2xs));
--cx-padding-x: var(--cx-pagination-padding-x, var(--cx-space-2xs));
--cx-min-size: var(--cx-pagination-min-size, 2.5rem);
--cx-gap: var(--cx-pagination-gap, var(--cx-space-xs));
--cx-idle-fg-color: var(--cx-pagination-idle-fg-color, var(--cx-fg-main));
--cx-idle-bg-color: var(--cx-pagination-idle-bg-color, var(--cx-bg-main));
--cx-hover-fg-color: var(--cx-pagination-hover-fg-color, var(--cx-fg-main));
--cx-hover-bg-color: var(--cx-pagination-hover-bg-color, var(--cx-bg-even));
--cx-active-fg-color: var(--cx-pagination-active-fg-color, var(--cx-fg-active));
--cx-active-bg-color: var(--cx-pagination-active-bg-color, var(--cx-bg-active));
--cx-active-border-color: var(--cx-pagination-active-border-color, var(--cx-bg-active));
--cx-disabled-fg-color: var(--cx-pagination-disabled-fg-color, var(--cx-fg-slight));
--cx-disabled-bg-color: var(--cx-pagination-disabled-bg-color, var(--cx-bg-main));
--cx-disabled-border-color: var(--cx-pagination-disabled-border-color, var(--cx-border-subtle));
--cx-border-width: var(--cx-pagination-border-width, var(--cx-border-width-md));
--cx-border-color: var(--cx-pagination-border-color, var(--cx-border-subtle));
--cx-border-radius: var(--cx-pagination-border-radius, var(--cx-border-radius-md));
--cx-icon-size: var(--cx-pagination-icon-size, 1.125em);
--cx-focus-ring-offset: var(--cx-pagination-focus-ring-offset, 0px);
--cx-font-family: var(--cx-pagination-font-family, var(--cx-font-family-text));
--cx-font-size: var(--cx-pagination-font-size, var(--cx-font-size-md));
--cx-font-weight: var(--cx-pagination-font-weight, var(--cx-font-weight-strong));
--cx-line-height: var(--cx-pagination-line-height, var(--cx-line-height-md));

Sass variables

This component uses Sass variables in scss/config/_defaults.scss to define its defaults.

$pagination-border-radius:              $button-medium-border-radius;
$pagination-font:                       $button-medium-font;
$pagination-min-size:                   $button-medium-min-size;

$pagination-lg-border-radius:        $button-large-border-radius;
$pagination-lg-font:                 $button-large-font;
$pagination-lg-min-size:             $button-large-min-size;

$pagination-sm-border-radius:        $button-small-border-radius;
$pagination-sm-font:                 $button-small-font;
$pagination-sm-min-size:             $button-small-min-size;

$pagination-padding-y:                  var(--space-2xs);
$pagination-padding-x:                  var(--space-2xs);
$pagination-gap:                        var(--space-xs);
$pagination-border-width:               var(--border-width-md);
$pagination-border-color:               var(--border-subtle);
$pagination-icon-size:                  1.125em;

$pagination-idle-fg-color:              var(--fg-main);
$pagination-idle-bg-color:              var(--bg-main);
$pagination-hover-fg-color:             var(--fg-main);
$pagination-hover-bg-color:             var(--bg-even);
$pagination-active-fg-color:            var(--fg-active);
$pagination-active-bg-color:            var(--bg-active);
$pagination-active-border-color:        var(--bg-active);
$pagination-disabled-fg-color:          var(--fg-slight);
$pagination-disabled-bg-color:          var(--bg-main);
$pagination-disabled-border-color:      $pagination-border-color;

$pagination-focus-ring-offset:          0px;

$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;