Pagination

Overview

Style

Guidelines

Code

Accessibility

Demos

Importing

Usage

Implementation guidelines

rh-pagination

Importing

Usage

Implementation guidelines

rh-pagination

Importing

Add rh-pagination to your page with this import statement:

<script type="module">
  import '@rhds/elements/rh-pagination/rh-pagination.js';
</script>

Copy to Clipboard Wrap lines

To learn more about installing RHDS elements on your site using an import map read our getting started docs.

Lightdom CSS

This element requires you to load "Lightdom CSS" stylesheets for styling deeply slotted elements.

Note

Replace /path/to/ with path to the CSS file, whether local or CDN.

<link rel="stylesheet" href="/path/to/rh-pagination/rh-pagination-lightdom.css">

Implementation guidelines

Basic Structure

<rh-pagination> must have a nested <ol> element with at least one nested <li> and <a> element.
Each <a> element must have an href attribute that links to the corresponding page.

URL Structure Options

You can implement pagination URLs using any of these approaches:

Option 1: Hash fragments (recommended for client-side routing)

Example: example.redhat.com/search/#2, example.redhat.com/search/#3
If using query parameters, ensure the hash comes after: example.redhat.com/search/?q=test#2

Option 2: Query parameters

Example: example.redhat.com/search?page=2, example.redhat.com/search?page=3
Can be combined with other query parameters: example.redhat.com/search?q=test&page=2

Option 3: Path-based URLs

Example: example.redhat.com/search/page/2, example.redhat.com/search/page/3

Option 4: Manual control with `aria-current`

Set aria-current="page" on the current page's <a> element
Useful for server-side rendered pagination

How the Current Page is Determined

The component determines the active page in this order:

Looking for an aria-current="page" attribute on an <a> tag
Matching the full URL (pathname, search parameters, and hash) against each link's href
If no match is found, the component logs a warning: "could not determine current link"

Pagination allows users to navigate between pages of related content. Use it when content is too long for a single view. Authors must provide a single <ol> with <li><a> page links where the active page should have aria-current="page". Tab navigates between controls; Enter activates. Supports box and open variants, default and small sizes.

Slots 3

Slot Name	Summary	Description
`go-to-page`	Page input label	Expects short inline text labeling the page number input. Defaults to "Page". Should be localized for non-English contexts. Visually hidden at narrow widths but always exposed to screen readers via `aria-labelledby`.
`out-of`
`[default]`	Page link list	Expects a single `<ol>` containing `<li><a>` block elements for each page. The active page link must have `aria-current="page"` or match the current URL. Authors should ensure each link has descriptive text for assistive technology. The wrapping `<nav>` is announced as a landmark labeled by the `label` property; authors must keep labels unique when multiple paginations exist on a page. Note: [default] unnamed slots do not have a slot="name" attribute.

Attributes 8

Attribute	DOM Property	Description	Type	Default
`overflow`	`overflow`	Controls which end(s) of the page list are truncated with ellipsis. Accepts `'start'` \| `'end'` \| `'both'` \| `null`. Computed automatically from page count and current index. Reflected to the host attribute so light-DOM CSS can hide overflow `<li>` elements. Defaults to `null`.	`'start' \| 'end' \| 'both' \| null`	`null`
`label`	`label`	Accessible label for the `<nav>` landmark. Should be unique when multiple paginations exist on a page. Defaults to `'Page navigation'`.	`string`	`'Page navigation'`
`label-first`	`labelFirst`	Accessible label for the first-page stepper button. Used by screen readers. Defaults to `'first page'`.	`string`	`'first page'`
`label-previous`	`labelPrevious`	Accessible label for the previous-page stepper button. Used by screen readers. Defaults to `'previous page'`.	`string`	`'previous page'`
`label-next`	`labelNext`	Accessible label for the next-page stepper button. Used by screen readers. Defaults to `'next page'`.	`string`	`'next page'`
`label-last`	`labelLast`	Accessible label for the last-page stepper button. Used by screen readers. Defaults to `'last page'`.	`string`	`'last page'`
`size`	`size`	Controls pagination size. Accepts `'sm'` for smaller touch targets (WCAG AA) or `null` for default (WCAG AAA). Defaults to `null`.	`'sm' \| null`	`null`
`variant`	`variant`	Visual variant. Accepts `'open'` for transparent backgrounds with bottom borders, or `null` for the default box variant. Defaults to `null`.	`'open' \| null`	`null`

Methods 5

Method Name	Description
`first()`	Navigate to the first page
`prev()`	Navigate to the previous page
`next()`	Navigate to the next page
`last()`	Navigate to the last page
`go(page: 'first' \| 'prev' \| 'next' \| 'last' \| number)`	Navigate to a specific page

Events 0

None

CSS Shadow Parts 4

Part Name	Summary	Description
`numeric`		shared container for the numeric controls at all widths
`container`		pagination container
`numeric-middle`		container for the numeric control at medium screen widths
`numeric-end`		container for the numeric control at small and large screen widths

CSS Custom Properties 4

CSS Property	Description	Default
`--rh-color-icon-status-disabled`		`—`
`--rh-pagination-stepper-color`	Stepper icon color override	`var(--rh-color-gray-50, #707070)`
`--rh-pagination-background-focused`	Disabled stepper icon color	`—`
`--rh-pagination-accent-color`	--rh-pagination-accent-color Controls the accent color used for interactive elements and focus states. Defaults to `--rh-color-interactive-primary-default` (interactive blue). Usage guidelines: Sets outline color when page input field has focus Applied to bottom border of active/hovered page links Used for focus indicators on navigation controls Keep default for consistent interactive color across pages Customize only when brand guidelines require specific accent colors Ensure sufficient contrast with background (4.5:1 ratio minimum) Page link color override Page link focus color override Page link focus outline color override Stepper focus outline color override Stepper focus accent border color override Input focus border color override	`var(--rh-color-interactive-primary-default)`

Design Tokens 34

Token	Description	Copy
`--rh-length-3xl`	Stepper button size 48px length token	Full CSS Variable Permalink to this token
`--rh-space-xs`	4px spacer	Full CSS Variable Permalink to this token
`--rh-color-interactive-primary-hover`	Page link hover color	Full CSS Variable Permalink to this token
`--rh-color-interactive-primary-visited-default`	Page link visited color	Full CSS Variable Permalink to this token
`--rh-color-interactive-primary-visited-hover`	Page link visited hover color	Full CSS Variable Permalink to this token
`--rh-color-surface-lighter`	Page link background in light mode Stepper background in light mode Tertiary surface (light theme)	Full CSS Variable Permalink to this token
`--rh-color-surface-dark`	Tertiary surface (dark theme)	Full CSS Variable Permalink to this token
`--rh-color-text-primary-on-dark`	Stepper hover/focus icon color Primary text color for dark theme	Full CSS Variable Permalink to this token
`--rh-color-border-subtle-on-light`	Stepper hover border in dark mode Subtle border color (light theme)	Full CSS Variable Permalink to this token
`--rh-color-text-secondary-on-dark`	Stepper icon color in dark mode Secondary text color for dark theme	Full CSS Variable Permalink to this token
`--rh-font-family-heading`	Stepper typeface Heading font family	Full CSS Variable Permalink to this token
`--rh-font-size-heading-xs`	Stepper text size h6 heading font size	Full CSS Variable Permalink to this token
`--rh-border-width-lg`	Stepper hover/focus border width 3px border width: Example: Expanded Accordion panel	Full CSS Variable Permalink to this token
`--rh-color-border-interactive`	Stepper focus accent border color	Full CSS Variable Permalink to this token
`--rh-space-2xl`	Container row gap Pagination end margin at containers >= md 32px spacer	Full CSS Variable Permalink to this token
`--rh-length-2xl`	Stepper button size at small size Pagination block size 32px length token	Full CSS Variable Permalink to this token
`--rh-length-4xl`	Pagination inline size 64px length token	Full CSS Variable Permalink to this token
`--rh-color-surface-lightest`	Current page background in light mode Input background in light mode Primary surface (light theme)	Full CSS Variable Permalink to this token
`--rh-color-surface-darkest`	Current page background in dark mode Input background in dark mode Primary surface (dark theme)	Full CSS Variable Permalink to this token
`--rh-color-border-subtle`	Current page border color Input border color	Full CSS Variable Permalink to this token
`--rh-color-gray-60`	Stepper hover border in light mode Disabled icon color in dark mode Input bottom border in dark mode Secondary text (light theme)	Full CSS Variable Permalink to this token
`--rh-color-text-primary`	Page link text color Pagination text color	Full CSS Variable Permalink to this token
`--rh-color-interactive-primary-default`	Page link color Page link focus color Page link focus outline color Stepper focus outline color Input focus border color	Full CSS Variable Permalink to this token
`--rh-space-sm`	Pagination vertical spacing 6px spacer	Full CSS Variable Permalink to this token
`--rh-space-md`	Pagination horizontal spacing 8px spacer	Full CSS Variable Permalink to this token
`--rh-color-red-60`	Invalid input bottom border in light mode Dark brand red	Full CSS Variable Permalink to this token
`--rh-color-red-40`	Invalid input bottom border in dark mode Light brand red	Full CSS Variable Permalink to this token
`--rh-font-size-body-text-md`	Input text size Pagination text size 16px font size	Full CSS Variable Permalink to this token
`--rh-border-width-sm`	Stepper border width Input border width Total link underline width 1px border width; Example: Secondary CTA or Button	Full CSS Variable Permalink to this token
`--rh-color-gray-50`	Stepper icon color in light mode Stepper icon color Total link underline in light mode Subtle icon	Full CSS Variable Permalink to this token
`--rh-color-gray-40`	Disabled icon color in light mode Input bottom border in light mode Total link underline in dark mode Subtle icon (hover state)	Full CSS Variable Permalink to this token
`--rh-border-radius-default`	Stepper focus corner rounding Total link focus corner rounding 3px border radius; Example: Card	Full CSS Variable Permalink to this token
`--rh-border-width-md`	Stepper focus outline width Stepper focus accent border width Input focus border width Total link focus outline width 2px border width: Example: Alert	Full CSS Variable Permalink to this token
`--rh-space-lg`	Pagination horizontal margin Pagination start margin at containers >= 344px (custom) 16px spacer	Full CSS Variable Permalink to this token

Edit this page on GitHub

Other libraries

Feedback

Pagination

Note

Other libraries

Feedback

Related elements or patterns

Red Hat legal and privacy links

Red Hat legal and privacy links