Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Navigation

Pagination

Page navigation with buttons or real Vue router links.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add pagination

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import { ref } from 'vue'
import Pagination from './components/ui/pagination/Pagination.vue'

const page = ref(4)
const messages = {
  navigation: 'Results pages',
  previous: 'Previous page',
  next: 'Next page',
  page: (value: number) => `Go to page ${value}`,
}
</script>

<template>
  <Pagination v-model="page" :total-pages="5" :messages="messages" />
</template>

The selected-page background slides to the newly selected page, including when the page range or ellipses change, and it stays still when reduced motion is enabled.

When to use it

Search results

Move between server-backed result pages while retaining the current query.

Long tables

Keep page controls near the table they update.

More examples

Nuxt route pages

Each page number and available direction control is a real NuxtLink.

Nuxt route pages
<script setup lang="ts">
import { computed } from 'vue'
import { NuxtLink } from '#components'
import { useRoute } from '#imports'
import Pagination from './components/ui/pagination/index.vue'

const route = useRoute()
const currentPage = computed(() => Number(route.query.page ?? 1))
const messages = {
  navigation: 'Results pages',
  previous: 'Previous',
  next: 'Next',
  page: (n: number) => `Page ${n}`,
}
</script>

<template>
  <Pagination
    :model-value="currentPage"
    :total-pages="20"
    :messages="messages"
    :link-as="NuxtLink"
    :page-to="page => ({ query: { ...route.query, page } })"
  />
</template>

Results pages

Supply messages for every button and bind the current page.

Results pages
<script setup lang="ts">
import { ref } from 'vue'
import Pagination from './components/ui/pagination/Pagination.vue'

const page = ref(1)
const messages = {
  navigation: 'Search results pages',
  previous: 'Previous page',
  next: 'Next page',
  page: (n: number) => `Go to page ${n}`,
}
</script>

<template>
  <Pagination v-model="page" :total-pages="20" :messages="messages" />
</template>

Compact range

Fewer siblings make the control easier to fit in a narrow results column.

Compact range
<script setup lang="ts">
import { ref } from 'vue'
import Pagination from './components/ui/pagination/Pagination.vue'

const page = ref(8)
const messages = {
  navigation: 'Orders pages',
  previous: 'Previous',
  next: 'Next',
  page: (n: number) => `Page ${n}`,
}
</script>

<template>
  <Pagination
    v-model="page"
    :total-pages="35"
    :sibling-count="0"
    :boundary-count="1"
    :messages="messages"
  />
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

Pagination

Complete API for Pagination
NameType or signatureDefaultWhat it does
totalPagespropnumberRequiredTotal number of pages available.
messagespropPaginationMessagesRequiredSupply the text this component displays for its built-in actions and states.
siblingCountpropnumber | undefined1Number of pages shown beside the current page.
boundaryCountpropnumber | undefined1Number of pages kept visible at the beginning and end.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
linkAspropComponent | undefinedNot setRender available page controls as router links when paired with pageTo.
pageToprop((page: number) => unknown) | undefinedNot setIt renders buttons by default and router links when linkAs and pageTo are provided.
modelValuemodelnumber | undefined1Current value. Use v-model to keep it in sync with your page.
update:modelValueevent[value: number]—Requests a new model value from the parent.
previousslot((props: { disabled: boolean; }) => unknown) | undefinedOptionalContent for the previous area of Pagination.
nextslot((props: { disabled: boolean; }) => unknown) | undefinedOptionalContent for the next area of Pagination.
pageslot((props: { page: number; current: boolean; }) => unknown) | undefinedOptionalContent for the page area of Pagination.
ellipsisslot(() => unknown) | undefinedOptionalContent for the ellipsis area of Pagination.
Public type definitions
Public types
// packages/frameworks/vue/components/pagination/types.ts
// ------- IMPORTS -------

import type { Component } from 'vue'

// ------- TYPES -------

export interface PaginationMessages {
  navigation: string
  previous: string
  next: string
  page: (page: number) => string
}

export interface PaginationProps {
  totalPages: number
  messages: PaginationMessages
  siblingCount?: number
  boundaryCount?: number
  disabled?: boolean
  /** Render available page controls as router links when paired with pageTo. */
  linkAs?: Component
  pageTo?: (page: number) => unknown
}

export type PaginationItem = number | 'ellipsis-start' | 'ellipsis-end'

Implementation notes

  • Update the displayed result data when page changes; Pagination only manages page selection.
  • Reset or clamp the current page when filtering changes the total page count.
  • Enabled page and direction controls give slight press feedback.

Accessibility and localization

  • The messages object supplies navigation and button names; the current page has aria-current="page".

Source contract and editing guidance