Pagination

Patterns

Link-Based Pagination

When to use:

• pages are real navigable destinations

Composition notes:

• use PaginationItem asChild
• keep href generation in the parent feature

Trade-offs:

• strong navigation semantics
• routing complexity stays outside the component

import { ChevronLeft, ChevronRight } from '@vega-ui/icons';
import {
  Icon,
  Pagination,
  PaginationEllipsis,
  PaginationItem,
  PaginationListItem,
  PaginationTriggerIconButton,
} from '@vega-ui/react';
import { useEffect, useState } from 'react';

type PageItem = number | 'start-ellipsis' | 'end-ellipsis';

Button-Based Pagination

When to use:

• page state is entirely local or client-controlled

Composition notes:

• keep current page in parent state
• disable boundary triggers

Trade-offs:

• simple local control
• parent feature must still own canonical page state

import { ChevronLeft, ChevronRight } from '@vega-ui/icons';
import {
  Icon,
  Pagination,
  PaginationEllipsis,
  PaginationItem,
  PaginationListItem,
  PaginationTriggerIconButton,
} from '@vega-ui/react';
import { useState } from 'react';

type PageItem = number | 'start-ellipsis' | 'end-ellipsis';

Truncated Large Range

When to use:

• the page count is large and showing every page is noisy

Composition notes:

• keep first, current context, and last pages visible
• use ellipsis only as a gap indicator

Trade-offs:

• compact and scalable
• users lose direct access to every page button

import { ChevronLeft, ChevronRight, ChevronsLeft, ChevronsRight } from '@vega-ui/icons';
import {
  Button,
  Icon,
  Pagination,
  PaginationEllipsis,
  PaginationItem,
  PaginationListItem,
  PaginationTriggerIconButton,
  Text,
} from '@vega-ui/react';
import { useState } from 'react';

Comparison

Quick Decision Rule

Use Pagination for explicit page navigation across discrete result sets. Use PageControl for short carousel/step indicators and consider other patterns when the data is better served by infinite scroll or filters.

Pagination vs PageControl

• Use Pagination for result pages.
• Use PageControl for short step or carousel indicators.

Pagination vs infinite scroll

• Use Pagination when users need stable page positions and direct navigation.
• Use infinite scroll when seamless browsing matters more than discrete page boundaries.

Choose This Component When

• users navigate explicit page numbers or page boundaries
• routes or server queries map naturally to pages

Do Not Choose This Component When

• the interaction is a short carousel or onboarding stepper
• page numbers do not carry meaningful value in the product

Troubleshooting

The UI Shows A Current Page But Data Does Not Match It

Symptom

The highlighted page button and the actual data state drift apart.

Likely Cause

Pagination visuals were treated as the source of truth instead of the parent page state.

How To Verify

• inspect the parent routing or query-state logic
• compare the active page data with the rendered pagination controls

Fix

Make the parent feature authoritative and render pagination from that state.

Previous Or Next Controls Still Work At The Boundaries

Symptom

Users can click into invalid pages before page 1 or after the last page.

Likely Cause

Boundary disabled logic was not wired in the parent feature.

How To Verify

• test the first and last pages

Fix

Disable or omit the relevant trigger controls at boundaries.

The Ellipsis Feels Clickable But Should Not Be

Symptom

Users interpret the ellipsis as a page action.

Likely Cause

Styling or composition made PaginationEllipsis look like a real page item.

How To Verify

• compare ellipsis styling with page items

Fix

Keep ellipsis visually passive and reserve interactive styling for real navigation items.