Pagination

Add a pagination to handle pages.

Usage

Use a v-model to get a reactive page alongside a total which represents the total of items. You can also use the page-count prop to define the number of items per page which defaults to 10.

<script setup lang="ts">
const page = ref(1)
const items = ref(Array(55))
</script>

<template>
  <UPagination v-model="page" :page-count="5" :total="items.length" />
</template>

Max

Use the max prop to set a maximum of displayed pages. Defaults to 7, being the minimum.

<template>
  <UPagination :max="5" :page-count="5" :total="100" :model-value="1" />
</template>

Size

Use the size prop to change the size of the buttons.

<template>
  <UPagination size="sm" :model-value="1" :total="100" show-last show-first />
</template>

Links

Use the to property to transform buttons into links. Note that it must be a function that receives the page number and returns a route destination.

<script setup lang="ts">
const page = ref(1)
const items = ref(Array(50))
</script>

<template>
  <UPagination
    v-model="page"
    :page-count="5"
    :total="items.length"
    :to="(page: number) => ({
      query: { page },
      // Hash is specified here to prevent the page from scrolling to the top
      hash: '#links'
    })"
  />
</template>

Disabled

Use the disabled prop to disable all the buttons.

<template>
  <UPagination disabled :model-value="1" :total="100" show-last show-first />
</template>

Active / Inactive

Use the active-button and inactive-button props to customize the active and inactive buttons of the Pagination.

<template>
  <UPagination
    :active-button="{ variant: 'outline' }"
    :inactive-button="{ color: 'gray' }"
    :model-value="1"
    :total="100"
  />
</template>

Prev / Next

Use the prev-button and next-button props to customize the prev and next buttons of the Pagination.

<template>
  <UPagination
    :prev-button="{ icon: 'i-heroicons-arrow-small-left-20-solid', label: 'Prev', color: 'gray' }"
    :next-button="{ icon: 'i-heroicons-arrow-small-right-20-solid', trailing: true, label: 'Next', color: 'gray' }"
    :model-value="1"
    :total="100"
  />
</template>

First / Last

Use the first-button and last-button props to customize the first and last buttons of the Pagination.

<template>
  <UPagination
    :first-button="{ icon: 'i-heroicons-arrow-small-left-20-solid', label: 'First', color: 'gray' }"
    :last-button="{ icon: 'i-heroicons-arrow-small-right-20-solid', trailing: true, label: 'Last', color: 'gray' }"
    :model-value="1"
    :total="100"
    show-first
    show-last
  />
</template>

Slots

Prev / Next

Use the #prev and #next slots to set the content of the previous and next buttons.

<script setup lang="ts">
const page = ref(1)
const items = ref(Array(55))
</script>

<template>
  <UPagination v-model="page" :total="items.length" :ui="{ rounded: 'first-of-type:rounded-s-md last-of-type:rounded-e-md' }">
    <template #prev="{ onClick, canGoPrev }">
      <UTooltip text="Previous page">
        <UButton
          icon="i-heroicons-arrow-small-left-20-solid"
          color="primary"
          :ui="{ rounded: 'rounded-full' }"
          class="rtl:[&_span:first-child]:rotate-180 me-2"
          :disabled="!canGoPrev"
          @click="onClick"
        />
      </UTooltip>
    </template>

    <template #next="{ onClick, canGoNext }">
      <UTooltip text="Next page">
        <UButton
          icon="i-heroicons-arrow-small-right-20-solid"
          color="primary"
          :ui="{ rounded: 'rounded-full' }"
          class="rtl:[&_span:last-child]:rotate-180 ms-2"
          :disabled="!canGoNext"
          @click="onClick"
        />
      </UTooltip>
    </template>
  </UPagination>
</template>

First / Last

Use the #first and #last slots to set the content of the first and last buttons.

<script setup lang="ts">
const page = ref(1)
const items = ref(Array(55))
</script>

<template>
  <UPagination v-model="page" :total="items.length" :ui="{ rounded: 'first-of-type:rounded-s-md last-of-type:rounded-e-md' }">
    <template #first="{ onClick, canGoFirst }">
      <UTooltip text="First page">
        <UButton
          icon="i-heroicons-arrow-uturn-left"
          color="primary"
          :ui="{ rounded: 'rounded-full' }"
          class="rtl:[&_span:first-child]:rotate-180 me-2"
          :disabled="!canGoFirst"
          @click="onClick"
        />
      </UTooltip>
    </template>

    <template #last="{ onClick, canGoLast }">
      <UTooltip text="Last page">
        <UButton
          icon="i-heroicons-arrow-uturn-right-20-solid"
          color="primary"
          :ui="{ rounded: 'rounded-full' }"
          class="rtl:[&_span:last-child]:rotate-180 ms-2"
          :disabled="!canGoLast"
          @click="onClick"
        />
      </UTooltip>
    </template>
  </UPagination>
</template>

Props

Property	Type	Default	Required
modelValue	number	-	true
total	number	-	true
size	“md” | “2xs” | “xs” | “sm” | “lg” | “xl”	“md”	-
max	number	7	-
ui	{}	-	-
to	function	null	-
divider	string	“…”	-
pageCount	number	10	-
activeButton	ButtonProps	{}	-
inactiveButton	ButtonProps	{}	-
firstButton	ButtonProps	{}	-
lastButton	ButtonProps	{}	-
prevButton	ButtonProps	{}	-
nextButton	ButtonProps	{}	-
disabled	boolean	false	-
showFirst	boolean	false	-
showLast	boolean	false	-

ButtonProps

Property	Type	Default
type	string	-
block	boolean	-
label	string	-
loading	boolean	-
disabled	boolean	-
padded	boolean	-
size	“2xs” | “xs” | “sm” | “md” | “lg” | “xl”	“md”
color	string	-
variant	“link” | “outline” | “solid” | “soft” | “ghost”	-
icon	string	-
loadingIcon	string	-
leadingIcon	string	-
trailingIcon	string	-
trailing	boolean	-
leading	boolean	-
square	boolean	-
truncate	boolean	-
target	string	-
as	string	-
active	boolean	-
exact	boolean	-
exactQuery	boolean | “partial”	-
exactHash	boolean	-
inactiveClass	string	-
to	{}	-
href	{}	-
external	boolean	-
rel	string	“noopener noreferrer”
noRel	boolean	-
prefetchedClass	string	-
prefetch	boolean	-
prefetchOn	“visibility” | “interaction” | {}	-
noPrefetch	boolean	-
replace	boolean	-
custom	boolean	-
activeClass	string	-
exactActiveClass	string	-
ariaCurrentValue	“time” | “step” | “date” | “page” | “location” | “true” | “false”	-
viewTransition	boolean	-

Config

{
  wrapper: 'flex items-center -space-x-px',
  base: '',
  rounded: 'first:rounded-s-md last:rounded-e-md',
  default: {
    size: 'sm',
    activeButton: {
      color: 'primary'
    },
    inactiveButton: {
      color: 'white'
    },
    firstButton: {
      color: 'white',
      class: 'rtl:[&_span:first-child]:rotate-180',
      icon: 'i-heroicons-chevron-double-left-20-solid'
    },
    lastButton: {
      color: 'white',
      class: 'rtl:[&_span:last-child]:rotate-180',
      icon: 'i-heroicons-chevron-double-right-20-solid'
    },
    prevButton: {
      color: 'white',
      class: 'rtl:[&_span:first-child]:rotate-180',
      icon: 'i-heroicons-chevron-left-20-solid'
    },
    nextButton: {
      color: 'white',
      class: 'rtl:[&_span:last-child]:rotate-180',
      icon: 'i-heroicons-chevron-right-20-solid'
    }
  }
}