Pagination

Navigation for splitting long lists of content across multiple pages.

Usage

import {
  Pagination,
  PaginationList,
  PaginationItem,
  PaginationLink,
  PaginationEllipsis,
} from '@appica/ui-react/pagination'

<Pagination>
  <PaginationList>
    <PaginationItem>
      <PaginationLink href="?page=1" active>
        1
      </PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="?page=2">2</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationEllipsis />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="?page=10">10</PaginationLink>
    </PaginationItem>
  </PaginationList>
</Pagination>

Pagination is a set of semantic primitives — there's no hidden state, so you build the page list yourself and decide which links to show. Every part lives under @appica/ui-react/pagination:

Pagination — the <nav aria-label="pagination"> landmark that wraps the control.
PaginationList — the <ul> that lays the items out in a row.
PaginationItem — one <li> wrapping a link or the ellipsis.
PaginationLink — a page link. Mark the current page with active (it becomes a non-interactive aria-current="page" element); mark out-of-range prev/next controls with disabled.
PaginationEllipsis — a decorative "…" standing in for the pages collapsed out of a long range.

The variant (outline or soft) and size (sm/md/lg) set on the root flow to every link through context. PaginationLink is built on Base UI's useRender, so you can project each link onto your router's link — e.g. a Next.js Link — without losing its styling or active state.

Examples

Default

A typical truncated range: an icon previous control (disabled on the first page), the current page marked active, an ellipsis for the gap, the last page, and an icon next control. Prev/next are chevron icons — give each an aria-label, and className="px-0" squares the link up around the lone icon.

import {
  Pagination,
  PaginationList,
  PaginationItem,
  PaginationLink,
  PaginationEllipsis,
} from '@appica/ui-react/pagination'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

export default function PaginationDefault() {
  return (
    <Pagination>
      <PaginationList>
        <PaginationItem>
          <PaginationLink href="#!" aria-label="Go to previous page" className="px-0" disabled>
            <ChevronLeft />
          </PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#!" active>
            1
          </PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#!">2</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#!">3</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationEllipsis />
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#!">10</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#!" aria-label="Go to next page" className="px-0">
            <ChevronRight />
          </PaginationLink>
        </PaginationItem>
      </PaginationList>
    </Pagination>
  )
}

Variants

outline (the default) draws a bordered button for each page; soft drops the borders for a lighter, fill-on-hover look. The active page is filled in both.

import { Pagination, PaginationList, PaginationItem, PaginationLink } from '@appica/ui-react/pagination'

export default function PaginationVariants() {
  return (
    <div className="flex flex-col items-center gap-6">
      {(['outline', 'soft'] as const).map((variant) => (
        <Pagination key={variant} variant={variant}>
          <PaginationList>
            <PaginationItem>
              <PaginationLink href="#!" active>
                1
              </PaginationLink>
            </PaginationItem>
            <PaginationItem>
              <PaginationLink href="#!">2</PaginationLink>
            </PaginationItem>
            <PaginationItem>
              <PaginationLink href="#!">3</PaginationLink>
            </PaginationItem>
            <PaginationItem>
              <PaginationLink href="#!">4</PaginationLink>
            </PaginationItem>
          </PaginationList>
        </Pagination>
      ))}
    </div>
  )
}

Sizes

Three sizes — sm, md (default), and lg — scale each link's height, minimum width, and text together.

import { Pagination, PaginationList, PaginationItem, PaginationLink } from '@appica/ui-react/pagination'

export default function PaginationSizes() {
  return (
    <div className="flex flex-col items-center gap-6">
      {(['sm', 'md', 'lg'] as const).map((size) => (
        <Pagination key={size} size={size}>
          <PaginationList>
            <PaginationItem>
              <PaginationLink href="#!" active>
                1
              </PaginationLink>
            </PaginationItem>
            <PaginationItem>
              <PaginationLink href="#!">2</PaginationLink>
            </PaginationItem>
            <PaginationItem>
              <PaginationLink href="#!">3</PaginationLink>
            </PaginationItem>
          </PaginationList>
        </Pagination>
      ))}
    </div>
  )
}

With first & last

For long ranges, flank the prev/next controls with first and last jump buttons — double-chevron icons that skip straight to the ends. Each is icon-only, so it needs an aria-label and className="px-0".

import { Pagination, PaginationList, PaginationItem, PaginationLink } from '@appica/ui-react/pagination'
import { ChevronsLeft, ChevronLeft, ChevronRight, ChevronsRight } from '@appica/icons-react'

export default function PaginationFirstLast() {
  return (
    <div className="max-w-full scrollbar-none overflow-auto [&::-webkit-scrollbar]:hidden">
      <Pagination>
        <PaginationList>
          <PaginationItem>
            <PaginationLink href="#!" aria-label="Go to first page" className="px-0">
              <ChevronsLeft />
            </PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#!" aria-label="Go to previous page" className="px-0">
              <ChevronLeft />
            </PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#!">1</PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#!">2</PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#!" active>
              3
            </PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#!">4</PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#!">5</PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#!" aria-label="Go to next page" className="px-0">
              <ChevronRight />
            </PaginationLink>
          </PaginationItem>
          <PaginationItem>
            <PaginationLink href="#!" aria-label="Go to last page" className="px-0">
              <ChevronsRight />
            </PaginationLink>
          </PaginationItem>
        </PaginationList>
      </Pagination>
    </div>
  )
}

Controlled

Pagination holds no state of its own, so wire it to your own page state. Here the current page lives in useState, each link's onClick updates it instead of navigating, the active page reflects state, and prev/next disable at the bounds.

Page 1 of 5

'use client'

import * as React from 'react'
import { Pagination, PaginationList, PaginationItem, PaginationLink } from '@appica/ui-react/pagination'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

const TOTAL = 5

export default function PaginationControlled() {
  const [page, setPage] = React.useState(1)

  const go = (target: number) => (event: React.MouseEvent) => {
    event.preventDefault()
    setPage(Math.min(Math.max(target, 1), TOTAL))
  }

  return (
    <div className="flex flex-col items-center gap-3">
      <p className="text-foreground-muted text-sm">
        Page {page} of {TOTAL}
      </p>
      <Pagination>
        <PaginationList>
          <PaginationItem>
            <PaginationLink
              href="#!"
              aria-label="Go to previous page"
              className="px-0"
              disabled={page === 1}
              onClick={go(page - 1)}
            >
              <ChevronLeft />
            </PaginationLink>
          </PaginationItem>
          {Array.from({ length: TOTAL }, (_, index) => index + 1).map((p) => (
            <PaginationItem key={p}>
              <PaginationLink href="#!" active={p === page} aria-label={`Go to page ${p}`} onClick={go(p)}>
                {p}
              </PaginationLink>
            </PaginationItem>
          ))}
          <PaginationItem>
            <PaginationLink
              href="#!"
              aria-label="Go to next page"
              className="px-0"
              disabled={page === TOTAL}
              onClick={go(page + 1)}
            >
              <ChevronRight />
            </PaginationLink>
          </PaginationItem>
        </PaginationList>
      </Pagination>
    </div>
  )
}

Router links

For client-side routing, project each PaginationLink onto your framework's link via render — here a Next.js Link. The link keeps its styling and active handling while the router owns navigation; put the href on the Link and any class overrides on the PaginationLink wrapper. Mark the current page active (no Link needed — it's non-interactive).

import Link from 'next/link'
import { Pagination, PaginationList, PaginationItem, PaginationLink } from '@appica/ui-react/pagination'
import { ChevronLeft, ChevronRight } from '@appica/icons-react'

export default function PaginationRouter() {
  return (
    <Pagination>
      <PaginationList>
        <PaginationItem>
          <PaginationLink aria-label="Go to previous page" className="px-0" render={<Link href="?page=1" />}>
            <ChevronLeft />
          </PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink render={<Link href="?page=1" />}>1</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink active>2</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink render={<Link href="?page=3" />}>3</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink aria-label="Go to next page" className="px-0" render={<Link href="?page=3" />}>
            <ChevronRight />
          </PaginationLink>
        </PaginationItem>
      </PaginationList>
    </Pagination>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

The page list flows from the right, and the previous/next controls swap sides — point their chevrons the other way so they still read as "back" and "forward". For setup details and caveats, see the RTL guide.

API reference

Pagination is a set of styled HTML elements. Each part forwards every remaining prop to its underlying element (nav, ul, li, a, span), so any native attribute works here — the tables below list the Appica additions and the most common props.

Pagination

The navigation landmark. Renders a <nav role="navigation" aria-label="pagination"> and provides the variant/size context.

Prop	Type	Default	Description
`variant`	`'outline' \| 'soft'`	`'outline'`	Link style, shared with every link via context.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Link sizing, shared via context.
`children`	`ReactNode`	—	A single `PaginationList`.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

PaginationList

The list of items. Renders a <ul> laying the items out in a row.

Prop	Type	Default	Description
`children`	`ReactNode`	—	`PaginationItem`s.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

PaginationItem

One item's <li> wrapper.

Prop	Type	Default	Description
`children`	`ReactNode`	—	A `PaginationLink` or `PaginationEllipsis`.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

PaginationLink

A page link. Built on Base UI's useRender; renders an <a> unless you project it onto another element with render. Inherits variant/size from the root.

Prop	Type	Default	Description
`active`	`boolean`	`false`	Mark the current page. Renders a non-interactive, filled link with `aria-current="page"`.
`disabled`	`boolean`	`false`	Make the link non-interactive and dimmed (`aria-disabled`); used for out-of-range controls.
`href`	`string`	—	Navigation target (when rendered as an `<a>`).
`render`	`ReactElement \| (props, state) => ReactElement`	—	Render as your own element (e.g. a router `Link`) or a `<button>`.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

PaginationEllipsis

A "…" placeholder for collapsed pages. Decorative (aria-hidden), with an sr-only "More pages" label.

Prop	Type	Default	Description
`children`	`ReactNode`	ellipsis dots	Override the placeholder mark.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

Accessibility

Pagination renders a <nav> with aria-label="pagination", so it's exposed as a named navigation landmark.
The current page (active) carries aria-current="page" and is non-interactive, so it isn't announced as a destination.
disabled links set aria-disabled and drop out of the tab order — the right way to express an out-of-range Previous/Next control.
Controls without visible text — icon-only prev/next, for instance — need an aria-label.
The ellipsis is aria-hidden and keeps an sr-only "More pages" label for context.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback

Pagination

Usage

Examples

Default

Variants

Sizes

With first & last

Controlled

Router links

RTL

API reference

PaginationList

PaginationItem

PaginationLink

PaginationEllipsis

Accessibility