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.

Theming

Themable

This element uses Red Hat design system theming and can be used in themable contexts.

Slots 3

Slot Name	Summary	Description
`[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.
`go-to-page`	page input label text (go-to-page slot)	Label text preceding the page number input field. Defaults to "Page". Customize for internationalization. Visually hidden at very small widths but always accessible to screen readers via `aria-labelledby`.
`out-of`		summary: preposition text between page input and total (default: "of") description: \| Contains the text displayed between the current page input field and the total page count. Defaults to "of" but can be customized for internationalization or alternate phrasing.

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 `'borderless'` for transparent backgrounds with bottom borders, or `null` for the default box variant. Defaults to `null`.	`'borderless' \| null`	`null`

Methods 7

Method Name	Description
`fromAttribute(value: string \| null)`
`firstUpdated()`
`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 2

Part Name	Summary	Description
`container`		The outer flex container wrapping stepper buttons, nav, and numeric input
`numeric`		The container for the page input, separator text, and total page link

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`	Sets the disabled stepper color.	`—`
`--rh-pagination-accent-color`	Page link color override Page link focus color override Page link focus outline color override Sets the accent color for focus outlines Stepper focus accent border color override Input focus border color override	`var(--rh-color-interactive-primary-default)`

Design Tokens 35

Token	Description	Copy
`--rh-length-3xl`	Stepper button size 48px length token	Full CSS Variable Permalink to this token
`--rh-length-2xl`	Stepper button size at small size 32px length token	Full CSS Variable Permalink to this token
`--rh-color-interactive-primary-hover`		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-space-xl`	24px spacer	Full CSS Variable Permalink to this token
`--rh-space-xs`	4px spacer	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`	32px spacer	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 Pagination vertical spacing 6px spacer	Full CSS Variable Permalink to this token
`--rh-color-red-60`	Dark brand red	Full CSS Variable Permalink to this token
`--rh-color-red-40`	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-space-lg`	Pagination horizontal margin 16px spacer	Full CSS Variable Permalink to this token
`--rh-space-md`	Pagination horizontal spacing Pagination horizontal spacing 8px spacer	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`	Pagination focus outline 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

Edit this page on GitHub

Other libraries

Feedback

Pagination

Note

Other libraries

Feedback

Related elements or patterns

Red Hat footer

Red Hat legal and privacy links

Red Hat legal and privacy links