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

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

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

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

<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:

<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:

<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 through Sass variables at compile time.

Custom properties

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

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

Sass variables

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

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

$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:                 $button-large-font;

$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:                 $button-small-font;

$pagination-border-width:               var(--border-width-medium);
$pagination-margin-start:               calc(#{$pagination-border-width} * -1);
$pagination-border-color:               var(--border-main);

$pagination-fg-color:                   var(--fg-main);
$pagination-bg-color:                   var(--bg-main);
$pagination-focus-fg-color:             var(--fg-main);
$pagination-focus-bg-color:             var(--bg-main);
$pagination-hover-fg-color:             var(--fg-hover);
$pagination-hover-bg-color:             var(--bg-hover);
$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;