Pager

import { Pager } from '@tangible/ui';

Interactive docs and examples: Pager in Storybook.

Pager props

Other exports

• defaultPagerLabels: Required<PagerLabels>

Examples

• Simple Mode: Simple mode shows only Prev/Next buttons without page numbers.

• Full Mode: Full mode shows all page numbers. Best for small page counts.

• With Page Size Selector: With page size selector for adjustable items per page.

• Many Pages: Smart mode handles large page counts with ellipsis.

• Few Pages: With only a few pages, all numbers are shown.

• Single Page: Single page with both nav buttons disabled.

• Ends Mode: Ends mode always keeps the first and last page visible, with ellipsis collapsing the middle. Compare with smart mode, which windows around the current page.

• Localised Labels: Every announced string routes through labels — nav landmark name, button labels, and the role="status" live region that announces page changes. WCAG 2.5.3 Label in Name: the visible button text (previousText/nextText) must be contained in the accessible name (previous/next), or voice-control users can't activate the buttons by saying what they see — keep that containment when translating.

• Detached (text nav): variant="detached" spaces the segments apart instead of joining them into a connected group — the pill-style pagination common on front-ends, as opposed to the admin-table look flush gives.

  Prev/next carry no border or fill in this variant: they sit outside the group as ghost affordances rather than outline segments completing it.

• Detached (icon nav): The same variant with navStyle="icon" — prev/next reduce to bare chevrons.

• Variants compared: Both variants together, for comparison. The gap is the only structural difference in the number group — --tui-pager-nav-gap drives it, and the flush variant zeroes it.

  Note the distinct labels.navigation on each. Every Pager renders a <nav> landmark named "Pagination" by default, so two on one page are indistinguishable to a screen reader moving by landmark (axe flags it as landmark-unique). Any page with more than one Pager — the common case being one above and one below a long table — has to differentiate them.

• Simple mode, no info: showInfo={false} drops the "Page X of Y" region. Most useful in simple mode, where the status line repeats context the prev/next pair already implies — which is why it always rendered there and could not be removed.

  It governs the region, not the page size selector: that has its own condition (pageSizeOptions + onPageSizeChange).

• First / last (flush): showFirstLast adds dedicated first/last buttons outside prev/next, so the order reads « ‹ 1 2 3 › ». They are nav affordances rather than page numbers, so they take the same treatment as prev/next in both variants.

  In flush they join the connected group at the ends — which means prev and next are no longer the end segments. The border-collapse rules key off actual position rather than which kind of button it is, so the outer radius lands on the new ends without any special casing.

• First / last (icon nav): With navStyle="icon", first/last are double chevrons — system/chevron-left-double and system/chevron-right-double, added for this affordance. The doubling is what distinguishes them from prev/next at a glance.

• First / last (simple mode): Where first/last earn their keep most: simple mode has no numbered group at all, so without them the only way back to page 1 is to click Prev repeatedly.

• First / last (detached): Detached, for the ghost treatment on all four nav buttons at once.

• Go to page: showJump adds a go-to-page field for page counts where even first/last are slow. It commits on Enter or via its own submit button — not on blur, which would move the page out from under someone who tabbed away mid-edit.

  Out-of-range entries clamp rather than error: typing 999 here goes to page 40, and the Pager's existing role="status" region announces where the jump actually landed, so the correction is audible rather than silent. The field clears on commit — "Page X of Y" is what displays state, so the input never sits there disagreeing with a page reached some other way.

• Everything on: Everything at once: first/last, the numbered group, the info region, a page size selector and the jump field — the densest the Pager gets, and a check that the row still lays out sensibly when it wraps.

• Go to page, no info: The jump field with no info region — showInfo={false} removes "Page X of Y" and the page size selector, and the jump still sits at the trailing end. The nav owns the auto margin that pushes it there, so it does not matter which of the trailing regions render.

• Responsive (container query): The Pager is a container query container (container-name: tuiPager), so it responds to the width it is given rather than to the viewport — the same approach Card and Notice use.

  Two things happen as the space narrows:

  1. The nav wraps. Unconditionally, not below a breakpoint: the nav's width depends on mode, maxNumbers, showFirstLast and size, so no single threshold can promise it fits — mode="full" at 30 pages is wider than any sane breakpoint. Wrapping costs nothing while it fits, and the alternative is the nav pushing the page into horizontal scroll (WCAG 2.1 SC 1.4.10).
  2. Below 32rem, flush adopts the detached presentation. A connected group cannot wrap and still look like one: the collapse rules key off :first-child/:last-child, and CSS cannot identify the first item of a wrapped row, so a second row would open with a borderless, square-cornered box. Pills wrap correctly by construction.

  32rem is a design line rather than a derived number, so a narrow pager degrades slightly before it strictly has to. The rules sit at the same specificity as the flush block, so a consumer can override the call.

Other stories: Default, Icon Navigation, Sizes (interactive page).

Component API tokens

Read via fallback, never declared. Set one on an ancestor to restyle every instance under it.

• --tui-pager-gap
• --tui-pager-nav-gap
• --tui-pager-item-border
• --tui-pager-item-radius
• --tui-pager-jump-width