Pagination

PaginationGitHub
A list of buttons or links to navigate through pages.

Usage

Use the default-page prop or the v-model:page directive to control the current page.

<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" :total="100" />
</template>
The Pagination component uses some Button to display the pages, use color, variant and size props to style them.

Total

Use the total prop to set the total number of items in the list.

<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" :total="100" />
</template>

Items Per Page

Use the items-per-page prop to set the number of items per page. Defaults to 10.

<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" :items-per-page="20" :total="100" />
</template>

Sibling Count

Use the sibling-count prop to set the number of siblings to show. Defaults to 2.

<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" :sibling-count="1" :total="100" />
</template>

Show Edges

Use the show-edges prop to always show the ellipsis, first and last pages. Defaults to false.

<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" show-edges :sibling-count="1" :total="100" />
</template>

Show Controls

Use the show-controls prop to show the first, prev, next and last buttons. Defaults to true.

<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" :show-controls="false" show-edges :total="100" />
</template>

Color

Use the color prop to set the color of the inactive controls. Defaults to neutral.

<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" color="primary" :total="100" />
</template>

Variant

Use the variant prop to set the variant of the inactive controls. Defaults to outline.

<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" color="neutral" variant="subtle" :total="100" />
</template>

Active Color

Use the active-color prop to set the color of the active control. Defaults to primary.

<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" active-color="neutral" :total="100" />
</template>

Active Variant

Use the active-variant prop to set the variant of the active control. Defaults to solid.

<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" active-color="primary" active-variant="subtle" :total="100" />
</template>

Size

Use the size prop to set the size of the controls. Defaults to md.

<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" size="xl" :total="100" />
</template>

Disabled

Use the disabled prop to disable the pagination controls.

<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" :total="100" disabled />
</template>

Examples

With links

Use the to prop to transform buttons into links. Pass a function that receives the page number and returns a route destination.

<script setup lang="ts">
const page = ref(5)

function to(page: number) {
  return {
    query: {
      page
    },
    hash: '#with-links'
  }
}
</script>

<template>
  <UPagination v-model:page="page" :total="100" :to="to" :sibling-count="1" show-edges />
</template>
In this example we're adding the #with-links hash to avoid going to the top of the page.

API

Props

Prop Default Type
as'div'any

The element or component this component should render as.

firstIconappConfig.ui.icons.chevronDoubleLeft string | object

The icon to use for the first page control.

prevIconappConfig.ui.icons.chevronLeft string | object

The icon to use for the previous page control.

nextIconappConfig.ui.icons.chevronRight string | object

The icon to use for the next page control.

lastIconappConfig.ui.icons.chevronDoubleRight string | object

The icon to use for the last page control.

ellipsisIconappConfig.ui.icons.ellipsis string | object

The icon to use for the ellipsis control.

color'neutral' "error" | "neutral" | "primary" | "secondary" | "success" | "info" | "warning"

The color of the pagination controls.

variant'outline' "outline" | "solid" | "soft" | "subtle" | "ghost" | "link"

The variant of the pagination controls.

activeColor'primary' "error" | "neutral" | "primary" | "secondary" | "success" | "info" | "warning"

The color of the active pagination control.

activeVariant'solid' "outline" | "solid" | "soft" | "subtle" | "ghost" | "link"

The variant of the active pagination control.

showControlstrueboolean

Whether to show the first, previous, next, and last controls.

size "xs" | "sm" | "md" | "lg" | "xl"
to (page: number): string | RouteLocationAsRelativeGeneric | RouteLocationAsPathGeneric

A function to render page controls as links.

defaultPage number

The value of the page that should be active when initially rendered.

Use when you do not need to control the value state.

disabledboolean

When true, prevents the user from interacting with item

itemsPerPage10 number

Number of items per page

page number

The controlled value of the current page. Can be binded as v-model:page.

showEdgesfalseboolean

When true, always show first page, last page, and ellipsis

siblingCount2 number

Number of sibling should be shown around the current page

total0 number

Number of items in your list

ui { root?: ClassNameValue; list?: ClassNameValue; ellipsis?: ClassNameValue; label?: ClassNameValue; first?: ClassNameValue; prev?: ClassNameValue; item?: ClassNameValue; next?: ClassNameValue; last?: ClassNameValue; }

Slots

Slot Type
first{}
prev{}
next{}
last{}
ellipsis{ ui: object; }
item{ page: number; pageCount: number; item: { type: "ellipsis"; } | { type: "page"; value: number; }; index: number; }

Emits

Event Type
update:page[value: number]

Theme

app.config.ts
export default defineAppConfig({
  ui: {
    pagination: {
      slots: {
        root: '',
        list: 'flex items-center gap-1',
        ellipsis: 'pointer-events-none',
        label: 'min-w-5 text-center',
        first: '',
        prev: '',
        item: '',
        next: '',
        last: ''
      }
    }
  }
})
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        pagination: {
          slots: {
            root: '',
            list: 'flex items-center gap-1',
            ellipsis: 'pointer-events-none',
            label: 'min-w-5 text-center',
            first: '',
            prev: '',
            item: '',
            next: '',
            last: ''
          }
        }
      }
    })
  ]
})

Changelog

dd81d — feat: add data-slot attributes (#5447)

63c0a — feat: expose ui in slot props where used (#5207)

62f64 — fix: make ellipsis non-interactive (#5081)

61b60 — feat: allow passing a component instead of a name (#4766)

5cb65 — feat: import @nuxt/ui-pro components

4dd56 — fix: match default button size (#4350)

e6e51 — fix: class should have priority over ui prop

39c86 — fix: refactor types after @nuxt/module-builder upgrade (#3855)

NavigationMenu

A list of links that can be displayed horizontally or vertically.

Stepper

A set of steps that are used to indicate progress through a multi-step process.