Pagination
updatedPage navigation with previous and next, ellipses for skipped pages, Button's variants and five sizes.
Open Props in the corner of the example to try variant, activeVariant, color, activeColor, size and disabled.
The current page and the rest take separate Button variants and colours: variant and color for the other pages and the arrows, active-variant and active-color for the current one — ghost neutral and solid primary by default. Every part also takes its own, which wins over the root's.
size runs xs to xl, Button's heights, 28 to 48px. A page is at least square, so a longer number widens it rather than squeezing.
Installation
Usage
<script setup lang="ts">
import { ref } from 'vue'
import {
Pagination,
PaginationContent,
PaginationEllipsis,
PaginationItem,
PaginationLink,
PaginationNext,
PaginationPrevious,
} from '@/components/ui/pagination'
const page = ref(1)
</script>
<template>
<Pagination v-model:page="page" :total="100" :items-per-page="10">
<PaginationContent v-slot="{ items }">
<PaginationItem>
<PaginationPrevious />
</PaginationItem>
<PaginationItem v-for="(item, index) in items" :key="item.type === 'page' ? item.value : `ellipsis-${index}`">
<PaginationLink v-if="item.type === 'page'" :value="item.value" />
<PaginationEllipsis v-else />
</PaginationItem>
<PaginationItem>
<PaginationNext />
</PaginationItem>
</PaginationContent>
</Pagination>
</template>
total and items-per-page give the page count; the content's items lists what to render, pages and ellipses, for the current page. It is a nav around a list: PaginationItem is the li that holds a link, an arrow or an ellipsis.
Examples
Edges and siblings
show-edges keeps the first and last page listed and puts an ellipsis where pages are skipped. sibling-count sets how many pages sit on each side of the current one, 2 by default.
Page 12 of 25
Links
With as-child, a page renders your own a or router link, so each page has a URL. The pagination still tracks the page it moves to.
API Reference
Pagination
class is also accepted on every part and merged over its classes with tailwind-merge.
| Prop | Default | Type and description |
|---|---|---|
| itemsPerPage* | — | numberItems on one page. With |
| page | — | numberThe current page, bound with |
| defaultPage | — | numberThe page shown at first when |
| total | — | numberNumber of items across all pages. |
| siblingCount | — | numberPages listed on each side of the current one. |
| disabled | — | booleanDisables every page and both arrows. |
| showEdges | — | booleanAlways lists the first and last page, with an ellipsis for the pages skipped between. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| variant | "ghost" | PaginationVariantButton variant of the other pages and the arrows. |
| activeVariant | "solid" | PaginationVariantButton variant of the current page. |
| color | "neutral" | PaginationColorColour of the other pages and the arrows. |
| activeColor | "primary" | PaginationColorColour of the current page. |
| size | "md" | PaginationSizeHeight of every part, from 28px for |
| Event | Payload and description |
|---|---|
| update:page | [value: number]Fires when another page is chosen. |
| Slot | Scope and description |
|---|---|
| default | { page: number; pageCount: number; }The content. Receives |
PaginationContent
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | "ul" | AsTag | ComponentThe element to render, a |
| Slot | Scope and description |
|---|---|
| default | { items: ({ type: "ellipsis"; } | { type: "page"; value: number; })[]; }The items. Receives |
PaginationLink
| Prop | Default | Type and description |
|---|---|---|
| value* | — | numberThe page this link goes to. |
| asChild | — | booleanRender the single child, an |
| as | — | AsTag | ComponentThe element or component to render. |
| variant | — | PaginationVariantOverrides the root's |
| activeVariant | — | PaginationVariantOverrides the root's |
| color | — | PaginationColorOverrides the root's |
| activeColor | — | PaginationColorOverrides the root's |
| size | — | PaginationSizeOverrides the root's |
| Slot | Scope and description |
|---|---|
| default | {}The label, the page number by default. |
PaginationPrevious
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a button, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| variant | — | PaginationVariantOverrides the root's |
| color | — | PaginationColorOverrides the root's |
| size | — | PaginationSizeOverrides the root's |
| Slot | Scope and description |
|---|---|
| default | {}The label and chevron. |
PaginationEllipsis
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| size | — | PaginationSizeOverrides the root's |
| Slot | Scope and description |
|---|---|
| default | {}The mark, three dots and a screen-reader label by default. |
PaginationItem
| Slot | Scope and description |
|---|---|
| default | {}A link, an arrow or an ellipsis. |
PaginationNext
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a button, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| variant | — | PaginationVariantOverrides the root's |
| color | — | PaginationColorOverrides the root's |
| size | — | PaginationSizeOverrides the root's |
| Slot | Scope and description |
|---|---|
| default | {}The label and chevron. |
class is also accepted on every part and merged over its classes with tailwind-merge.
Props
- itemsPerPage*
numberItems on one page. Withtotal, sets the page count.- page
numberThe current page, bound withv-model:page.- defaultPage
numberThe page shown at first whenv-model:pageis not used.- total
numberNumber of items across all pages.- siblingCount
numberPages listed on each side of the current one.- disabled
booleanDisables every page and both arrows.- showEdges
booleanAlways lists the first and last page, with an ellipsis for the pages skipped between.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- variant
"ghost" PaginationVariantButton variant of the other pages and the arrows.- activeVariant
"solid" PaginationVariantButton variant of the current page.- color
"neutral" PaginationColorColour of the other pages and the arrows.- activeColor
"primary" PaginationColorColour of the current page.- size
"md" PaginationSizeHeight of every part, from 28px forxsto 48px forxl, as Button'sxstoxl.
Emits
- update:page
[value: number]Fires when another page is chosen.
Slots
- default
{ page: number; pageCount: number; }The content. ReceivespageandpageCount.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
"ul" AsTag | ComponentThe element to render, aulby default.
Slots
- default
{ items: ({ type: "ellipsis"; } | { type: "page"; value: number; })[]; }The items. Receivesitems: each is{ type: 'page', value }or{ type: 'ellipsis' }.
Props
- value*
numberThe page this link goes to.- asChild
booleanRender the single child, anaor a router link, instead of a button, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- variant
PaginationVariantOverrides the root'svariantwhile this page is not current.- activeVariant
PaginationVariantOverrides the root'sactive-variantwhile this page is current.- color
PaginationColorOverrides the root'scolor.- activeColor
PaginationColorOverrides the root'sactive-color.- size
PaginationSizeOverrides the root'ssize.
Slots
- default
{}The label, the page number by default.
Props
- asChild
booleanRender the single child instead of a button, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- variant
PaginationVariantOverrides the root'svariant.- color
PaginationColorOverrides the root'scolor.- size
PaginationSizeOverrides the root'ssize.
Slots
- default
{}The label and chevron.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- size
PaginationSizeOverrides the root'ssize.
Slots
- default
{}The mark, three dots and a screen-reader label by default.
Slots
- default
{}A link, an arrow or an ellipsis.
Props
- asChild
booleanRender the single child instead of a button, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- variant
PaginationVariantOverrides the root'svariant.- color
PaginationColorOverrides the root'scolor.- size
PaginationSizeOverrides the root'ssize.
Slots
- default
{}The label and chevron.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| pagination | data-size | The nav. |
| pagination-content | — | The list. |
| pagination-item | — | A list item. |
| pagination-link | data-variant, data-color, data-size, data-selected | A page. data-selected marks the current one. |
| pagination-previous | data-variant, data-color, data-size | The arrow to the previous page. |
| pagination-next | data-variant, data-color, data-size | The arrow to the next page. |
| pagination-ellipsis | data-size | Pages skipped. |
Accessibility
The root is a nav labelled "Pagination"; pass aria-label to name it after what it pages through. The current page carries aria-current="page", each page is announced as "Page 3", the arrows as "Previous Page" and "Next Page", and an ellipsis reads "More pages". The arrows are disabled on the first and last page.