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