Pagination

updated

Page navigation with previous and next, ellipses for skipped pages, Button's variants and five sizes.

Demo

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.

With edges

Page 12 of 25

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.

Links

API Reference

Data attributes

data-slotAttributesDescription
paginationdata-sizeThe nav.
pagination-content—The list.
pagination-item—A list item.
pagination-linkdata-variant, data-color, data-size, data-selectedA page. data-selected marks the current one.
pagination-previousdata-variant, data-color, data-sizeThe arrow to the previous page.
pagination-nextdata-variant, data-color, data-sizeThe arrow to the next page.
pagination-ellipsisdata-sizePages 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.

Changelog

  1. registry 0.22.0

    13863fd — A disabled Pagination disables its as-child link pages as well: they carry aria-disabled, look disabled and do not navigate. Button pages carry aria-disabled next to their native disabled.

  2. registry 0.13.0

    93e57a0 — Every size on the control scale is named xs to xl; default and the bare icon are gone. To move over:

    - Button: size="default" becomes size="md", or leave size out; size="icon" becomes size="icon-md". The full set is xs to xl and icon-xs to icon-xl. Toggle, ToggleGroup, ToggleGroupItem, the Toolbar parts, AlertDialogAction, AlertDialogCancel and ToastAction take the same names; Button, Toggle and ToggleGroup default to md, the Toolbar parts keep sm and ToastAction keeps xs. InputGroupButton keeps its own xs, sm, icon-xs and icon-sm, 24 and 32px to fit inside the group, xs by default. Pagination hands its md to Button as it is. Button, Toggle and ToggleGroupItem set data-variant, data-color and data-size even when you leave them at their defaults. - AlertDialogContent: size="default" becomes size="md", still the default; sm is unchanged. The size option of useConfirm's confirm, alert and prompt takes the same names. - Table and DataTable: density becomes size, data-density becomes data-size, and the TableDensity type is now TableSize. sm, md and lg keep their 36, 44 and 52px rows; xs (28px) and xl (60px) are new, and DataTable's virtual row estimates cover them. The cells' padding above and below the text is now --table-cell-py on the table: 8px as before, 3px at xs. At xs, DataTable's sort buttons and expand and group toggles shrink to fit the row. The table-density example is now table-sizes. - DrawerMenu: size takes xs to xl like Menu and reads the control scale, plus room for a thumb. sm, md and lg keep their 40, 48 and 56px rows, padding and icons; xs is 36px and xl 64px. Overriding a --control-* token on :root now resizes DrawerMenu rows as well. - Select and Combobox: the list opens at the trigger's or anchor's size instead of always at md, so <SelectTrigger size="xl"> opens an xl list. size on SelectContent or ComboboxList picks another. Behind an as-child button, set size on ComboboxAnchor to match the button. The Select list now sets its menu variables on SelectContent instead of its viewport, so a class such as [--menu-item-height:2.5rem] on SelectContent reaches the items. - Input, Textarea, InputFloating, SelectTrigger, ComboboxAnchor and Separator set data-size with the default filled in, and the anchor sets data-variant too. With as-child, the anchor leaves the button's own data-variant and data-size alone.

  3. registry 0.12.0

    c79028b — The control scale is now a set of tokens: --control-height-*, --control-padding-*, --control-icon-* and --control-gap-* for xs to xl, added to :root by the tokens item. Button, Input, InputFloating, Select, Combobox, InputNumber, TagsInput, PinInput, InputTime, InputGroup, Menu, Tabs, ColorPicker and Pagination read them, so overriding one on :root resizes every control of that size.

    Some sizes that strayed from the scale now follow it. Button icons are 20px at lg and xl instead of 16px, and so are the icons of Toggle, ToggleGroup, Toolbar and Pagination at those sizes. The gap between an icon and its label is 6, 8, 8, 10 and 12px from xs to xl, about half the icon, everywhere that has one: Button and the components built on it (where it was 4, 6, 8, 8 and 8px), Menu items and the Select, Combobox and Command lists (8, 10, 12, 12 and 12px), and Tabs triggers (6, 8, 8, 8 and 10px). Inset and checkbox or radio items move their labels with it, so they stay in line with items that have an icon. Everything else keeps its size.