Pagination

Page navigation with previous, next, first and last links, numbered pages and an ellipsis for skipped ranges.

1
---
2
import { Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious } from '@bejamas/registry/ui/pagination';
3
---
4

5
<Pagination>
6
  <PaginationContent>
7
    <PaginationItem><PaginationPrevious href="#" /></PaginationItem>
8
    <PaginationItem><PaginationLink href="#">1</PaginationLink></PaginationItem>
9
    <PaginationItem><PaginationLink href="#" isActive>2</PaginationLink></PaginationItem>
10
    <PaginationItem><PaginationLink href="#">3</PaginationLink></PaginationItem>
11
    <PaginationItem><PaginationEllipsis /></PaginationItem>
12
    <PaginationItem><PaginationNext href="#" /></PaginationItem>
13
  </PaginationContent>
14
</Pagination>

Installation

bunx bejamas add pagination

npx bejamas add pagination

pnpm dlx bejamas add pagination

yarn dlx bejamas add pagination

Usage

1
---
2
import {
3
  Pagination,
4
  PaginationContent,
5
  PaginationEllipsis,
6
  PaginationItem,
7
  PaginationLink,
8
  PaginationNext,
9
  PaginationPrevious,
10
} from '@bejamas/registry/ui/pagination';
11
---
12

13
<Pagination>
14
  <PaginationContent>
15
    <PaginationItem>
16
      <PaginationPrevious href="?page=1" />
17
    </PaginationItem>
18
    <PaginationItem>
19
      <PaginationLink href="?page=1">1</PaginationLink>
20
    </PaginationItem>
21
    <PaginationItem>
22
      <PaginationLink href="?page=2" isActive>2</PaginationLink>
23
    </PaginationItem>
24
    <PaginationItem>
25
      <PaginationLink href="?page=3">3</PaginationLink>
26
    </PaginationItem>
27
    <PaginationItem>
28
      <PaginationEllipsis />
29
    </PaginationItem>
30
    <PaginationItem>
31
      <PaginationNext href="?page=3" />
32
    </PaginationItem>
33
  </PaginationContent>
34
</Pagination>

Rendering pages

Pagination is plain links and ships no JavaScript. Work out the pages on the server and map them to items:

1
---
2
const current = Number(Astro.url.searchParams.get('page') ?? 1);
3
const total = 10;
4
const pages = [...new Set([1, current - 1, current, current + 1, total])]
5
  .filter((page) => page >= 1 && page <= total)
6
  .sort((a, b) => a - b);
7
---
8

9
<Pagination>
10
  <PaginationContent>
11
    <PaginationItem>
12
      <PaginationPrevious href={`?page=${current - 1}`} disabled={current === 1} />
13
    </PaginationItem>
14
    {pages.map((page, index) => (
15
      <>
16
        {index > 0 && page - pages[index - 1] > 1 && (
17
          <PaginationItem><PaginationEllipsis /></PaginationItem>
18
        )}
19
        <PaginationItem>
20
          <PaginationLink href={`?page=${page}`} isActive={page === current}>{page}</PaginationLink>
21
        </PaginationItem>
22
      </>
23
    ))}
24
    <PaginationItem>
25
      <PaginationNext href={`?page=${current + 1}`} disabled={current === total} />
26
    </PaginationItem>
27
  </PaginationContent>
28
</Pagination>

Props

Prop	Type	Default
`class`	`string`	`""`

Examples

First and last

PaginationFirst and PaginationLast jump to either end. Pass disabled to the controls that lead nowhere; they render without an href and with aria-disabled="true".

1
---
2
import { Pagination, PaginationContent, PaginationEllipsis, PaginationFirst, PaginationItem, PaginationLast, PaginationLink, PaginationNext, PaginationPrevious } from '@bejamas/registry/ui/pagination';
3
---
4

5
<Pagination>
6
  <PaginationContent>
7
    <PaginationItem><PaginationFirst href="#" disabled /></PaginationItem>
8
    <PaginationItem><PaginationPrevious href="#" disabled /></PaginationItem>
9
    <PaginationItem><PaginationLink href="#" isActive>1</PaginationLink></PaginationItem>
10
    <PaginationItem><PaginationLink href="#">2</PaginationLink></PaginationItem>
11
    <PaginationItem><PaginationLink href="#">3</PaginationLink></PaginationItem>
12
    <PaginationItem><PaginationEllipsis /></PaginationItem>
13
    <PaginationItem><PaginationLink href="#">10</PaginationLink></PaginationItem>
14
    <PaginationItem><PaginationNext href="#" /></PaginationItem>
15
    <PaginationItem><PaginationLast href="#" /></PaginationItem>
16
  </PaginationContent>
17
</Pagination>

Icon only

Set text="" on the previous, next, first and last controls to render square icon buttons. Their aria-label still names the destination.

1
---
2
import { Pagination, PaginationContent, PaginationEllipsis, PaginationFirst, PaginationItem, PaginationLast, PaginationLink, PaginationNext, PaginationPrevious } from '@bejamas/registry/ui/pagination';
3
---
4

5
<Pagination>
6
  <PaginationContent>
7
    <PaginationItem><PaginationFirst href="#" text="" disabled /></PaginationItem>
8
    <PaginationItem><PaginationPrevious href="#" text="" disabled /></PaginationItem>
9
    <PaginationItem><PaginationLink href="#" isActive>1</PaginationLink></PaginationItem>
10
    <PaginationItem><PaginationLink href="#">2</PaginationLink></PaginationItem>
11
    <PaginationItem><PaginationLink href="#">3</PaginationLink></PaginationItem>
12
    <PaginationItem><PaginationEllipsis /></PaginationItem>
13
    <PaginationItem><PaginationLink href="#">10</PaginationLink></PaginationItem>
14
    <PaginationItem><PaginationNext href="#" text="" /></PaginationItem>
15
    <PaginationItem><PaginationLast href="#" text="" /></PaginationItem>
16
  </PaginationContent>
17
</Pagination>

Outlined

variant overrides the default ghost (inactive) and outline (active) button variants.

1
---
2
import { Pagination, PaginationContent, PaginationEllipsis, PaginationFirst, PaginationItem, PaginationLast, PaginationLink, PaginationNext, PaginationPrevious } from '@bejamas/registry/ui/pagination';
3
---
4

5
<Pagination>
6
  <PaginationContent>
7
    <PaginationItem><PaginationFirst href="#" text="" variant="outline" disabled /></PaginationItem>
8
    <PaginationItem><PaginationPrevious href="#" text="" variant="outline" disabled /></PaginationItem>
9
    <PaginationItem><PaginationLink href="#" variant="default" isActive>1</PaginationLink></PaginationItem>
10
    <PaginationItem><PaginationLink href="#" variant="outline">2</PaginationLink></PaginationItem>
11
    <PaginationItem><PaginationLink href="#" variant="outline">3</PaginationLink></PaginationItem>
12
    <PaginationItem><PaginationEllipsis /></PaginationItem>
13
    <PaginationItem><PaginationLink href="#" variant="outline">10</PaginationLink></PaginationItem>
14
    <PaginationItem><PaginationNext href="#" text="" variant="outline" /></PaginationItem>
15
    <PaginationItem><PaginationLast href="#" text="" variant="outline" /></PaginationItem>
16
  </PaginationContent>
17
</Pagination>

Simple

1
---
2
import { Pagination, PaginationContent, PaginationItem, PaginationLink } from '@bejamas/registry/ui/pagination';
3
---
4

5
<Pagination>
6
  <PaginationContent>
7
    <PaginationItem><PaginationLink href="#">1</PaginationLink></PaginationItem>
8
    <PaginationItem><PaginationLink href="#" isActive>2</PaginationLink></PaginationItem>
9
    <PaginationItem><PaginationLink href="#">3</PaginationLink></PaginationItem>
10
    <PaginationItem><PaginationLink href="#">4</PaginationLink></PaginationItem>
11
    <PaginationItem><PaginationLink href="#">5</PaginationLink></PaginationItem>
12
  </PaginationContent>
13
</Pagination>

API Reference

Parts

Part	Element	Description
`Pagination`	`<nav>`	Landmark with `aria-label="pagination"`
`PaginationContent`	`<ul>`	Row of items
`PaginationItem`	`<li>`	Wraps one link or the ellipsis
`PaginationLink`	`<a>`	A page link, styled as a `Button`
`PaginationPrevious`, `PaginationNext`	`<a>`	Adjacent page links with a chevron and a label
`PaginationFirst`, `PaginationLast`	`<a>`	First and last page links with a double chevron and a label
`PaginationEllipsis`	`<span>`	Marks a skipped range of pages

PaginationLink

PaginationPrevious, PaginationNext, PaginationFirst and PaginationLast take the same props.

Prop	Type	Default	Description
`href`	`string`		Page URL
`isActive`	`boolean`	`false`	Marks the current page with `aria-current="page"`
`disabled`	`boolean`	`false`	Drops the `href` and sets `aria-disabled="true"`
`size`	`"default" \| "sm" \| "lg" \| "icon" \| "icon-sm" \| "icon-lg"`	`"icon"`	Button size
`variant`	`"default" \| "outline" \| "secondary" \| "ghost" \| "destructive" \| "link"`	`"outline"` when active, `"ghost"` otherwise	Button variant

PaginationPrevious, PaginationNext, PaginationFirst, PaginationLast

Prop	Type	Default	Description
`text`	`string`	`"Previous"`, `"Next"`, `"First"`, `"Last"`	Visible label, hidden below the `sm` breakpoint. Pass `""` for an icon-only control
`aria-label`	`string`	`"Go to previous page"`, `"Go to next page"`, `"Go to first page"`, `"Go to last page"`	Accessible name
`size`	Button size	`"default"`, or `"icon"` when `text` is empty	Button size

Accessibility

The root is a <nav> landmark labelled pagination.
The current page link has aria-current="page", so screen readers announce it as the current page.
Previous, next, first and last links have an aria-label that names their destination.
Disabled controls have no href, so they are skipped by the keyboard, and aria-disabled="true" for assistive technology.
The ellipsis is hidden from assistive technology.

Keyboard

Every page is a native link, so no script is needed.

Key	Action
`Tab` / `Shift` + `Tab`	Move focus to the next / previous link
`Enter`	Follow the focused link

Data Attributes

Attribute	Element	Description
`data-active`	link	`"true"` on the current page, `"false"` otherwise
`aria-current`	link	`"page"` on the current page
`aria-disabled`	link	`"true"` when `disabled`