Bridge UI

Pagination

Page controls for lists and tables with numbered pages or simple prev/next.

Introduction

Pagination provides previous/next controls with labels and page numbers for lists and tables. Use numbered mode when you know the total page count, or mode="simple" for cursor-style APIs that only expose next/previous. Previous and Next resolve through the i18n adapter.

When to use: Paged tables, search results, and any list that splits into discrete pages. DataTable renders its own chrome pager when page is set. Prefer Link for a single destination and Tabs for switching peer views on the same level.

Use the framework selector in the site header to switch between React and Vue.

Import

import { Pagination } from "@bridge-ui/vue/Components/Pagination";
import { Pagination } from "@bridge-ui/react/Components/Pagination";

Basic usage

Pass count for the total number of pages. Control the page with page / onChange (React) or v-model (Vue). Pages are 1-based.

Variants

Choose the control style with variant: ghost (default), text, or outlined.

Rounded

rounded shapes ghost and text item corners and the outlined group / edge controls.

Siblings and boundaries

Tune the visible window with siblingCount (pages beside the current page) and boundaryCount (pages always shown at each end). Long ranges insert ellipsis placeholders.

Simple mode

For APIs that return next_cursor / prev_cursor instead of a page total, set mode="simple" and pass them as nextCursor / prevCursor. Bind the current cursor with cursor / onCursorChange (React) or v-model:cursor (Vue): it is set to nextCursor or prevCursor when the user navigates. A null cursor disables its control.

hasNext / hasPrevious override the cursor defaults. onNext / onPrevious (Vue: @next / @previous) still fire after the cursor update, so prev/next without cursors keeps working:

<Pagination
  mode="simple"
  :has-next="hasMore"
  v-on:next="loadNext"
  aria-label="Pagination"
  :has-previous="page > 1"
  v-on:previous="loadPrevious"
/>
<Pagination
  mode="simple"
  onNext={loadNext}
  hasNext={hasMore}
  hasPrevious={page > 1}
  aria-label="Pagination"
  onPrevious={loadPrevious}
/>

Sizes

Change density with size: sm, md (default), and lg.

Accessibility

  • The root renders a nav with aria-label="Pagination" by default. Override with your own aria-label when the page has more than one pagination control.
  • Page buttons use aria-label="Page N"; the current page also gets aria-current="page".
  • Previous and next controls show Previous and Next labels beside the chevrons.
  • Ellipsis placeholders are aria-hidden.

Anatomy

<nav aria-label="Pagination"> <!-- root -->
  <ul> <!-- list -->
    <li> <!-- previous -->
      <button> <!-- prev control: chevron + Previous / slots.prev -->
    <li> <!-- page or ellipsis -->
      <button|li> <!-- page item / ellipsis -->
    <li> <!-- next -->
      <button> <!-- next control: Next + chevron / slots.next -->
  </ul>
</nav>

Target parts with classes: root, list, item, prev, next, and ellipsis.

Breadcrumb, Link, Tabs, Stepper, Table, DataTable

API

Pagination

Prop Type Default Description
boundaryCount number 1 Pages always shown at the start and end.
classes PaginationClasses — Classes for root, list, item, prev, next, ellipsis.
color PaginationColor "dark" Optional text accent for the selected page. Selected surface comes from variant.
count number — Total pages (numbered mode).
cursor string \| null — Current cursor (mode="simple"). Set to nextCursor / prevCursor when the user navigates. Vue: v-model:cursor.
customProps PaginationCustomProps — Extra props for root, list, item, prev, next, icons, and ellipsis.
defaultPage number 1 Uncontrolled initial page (React numbered mode).
disabled boolean false Disable all controls.
hasNext boolean — Whether next is available (mode="simple"). Defaults to nextCursor !== null when nextCursor is passed.
hasPrevious boolean — Whether previous is available (mode="simple"). Defaults to prevCursor !== null when prevCursor is passed.
hideNextButton boolean false Hide the next control.
hidePrevButton boolean false Hide the previous control.
mode "numbered" \| "simple" "numbered" Numbered pages vs prev/next only.
modelValue number 1 Bound page with v-model (Vue numbered mode).
nextCursor string \| null — Cursor of the next page (mode="simple"). null disables next.
onChange (page: number) => void — Called when the page changes (React numbered mode). Vue emits change / update:modelValue.
onCursorChange (cursor: string \| null) => void — Called with nextCursor / prevCursor when next / previous is activated (React). Vue: update:cursor.
onNext () => void — Called when next is activated in simple mode (React). Vue: @next.
onPrevious () => void — Called when previous is activated in simple mode (React). Vue: @previous.
page number — Controlled page, 1-based (React numbered mode).
prevCursor string \| null — Cursor of the previous page (mode="simple"). null disables previous.
rounded PaginationRounded "md" Corner radius for ghost / text items and outlined group edges.
siblingCount number 1 Pages shown on each side of the current page.
size PaginationSize "md" Control size: sm, md, lg.
slots PaginationSlots — prev, next, ellipsis.
variant PaginationVariant "ghost" Visual style: ghost, text, outlined.