n-pagination

name	n-pagination
description	Pagination component for navigating through data pages. Invoke when user needs to implement pagination, page navigation, or data pagination controls in Naive UI.
metadata	{"author":"jiaiyan","version":"1.0.0"}

Naive UI Pagination Component

Long data's friend. Navigate through paginated data with ease.

When to Use

Use this component when:

• Data tables: Navigate through table data pages
• Search results: Browse through paginated search results
• Product listings: Navigate product catalog pages
• Content lists: Browse articles, posts, or other content

When to Invoke

Invoke this skill when:

• User needs to implement pagination
• User wants to customize page navigation
• User needs page size selection
• User wants quick jump functionality
• User asks about pagination configuration

Features

• Multiple Sizes: Small, medium, and large sizes
• Page Size Picker: Let users select items per page
• Quick Jumper: Jump to specific page number
• Simple Mode: Minimal pagination UI
• Custom Slots: Customize prev/next buttons and labels
• Item Count: Use total items instead of page count

API Reference

Pagination Props

Name	Type	Default	Description	Version
default-page	number	1	Current page in uncontrolled mode.
default-page-size	number	10	Page size in uncontrolled mode.
disabled	boolean	false	Whether to disable the pagination.
display-order	Array<string>	['pages', 'size-picker', 'quick-jumper']	Display order of parts.	2.32.2
goto	() => VNodeChild	undefined	Fast jump content render function.	2.34.3
item-count	number	undefined	Total number of items.
next	(info) => VNodeChild	undefined	Next page render function.
prev	(info) => VNodeChild	undefined	Previous page render function.
label	PaginationRenderLabel	undefined	Item content render function.	2.24.0
page-count	number	1	Total pages.
page-sizes	Array<number | object>	[10]	Items per page options.
page-size	number	undefined	Page size (controlled).
page-slot	number	9	Number of pages displayed.
page

Pagination Slots

Name	Parameters	Description	Version
goto	()	Fast jump text before quick jumper.	2.27.0
label	Label info	Item content.	2.24.0
next	(info)	Next page.
prev	(info)	Previous page.
prefix	(info)	Page prefix.
suffix	(info)	Page suffix.

Basic Usage

Basic Pagination

<template>
  <n-pagination v-model:page="page" :page-count="100" />
</template>

<script setup>
import { ref } from 'vue'

const page = ref(1)
</script>

Simple Mode

<template>
  <n-pagination v-model:page="page" :page-count="100" simple />
</template>

With Page Size Picker

<template>
  <n-pagination
    v-model:page="page"
    v-model:page-size="pageSize"
    :page-count="100"
    show-size-picker
    :page-sizes="[10, 20, 30, 40]"
  />
</template>

<script setup>
import { ref } from 'vue'

const page = ref(1)
const pageSize = ref(10)
</script>

Common Patterns

With Quick Jumper

<template>
  <n-pagination :page-count="100" show-quick-jumper>
    <template #goto>
      Go!
    </template>
  </n-pagination>
</template>

Using Item Count

<template>
  <n-pagination
    :item-count="201"
    :page-sizes="[10, 20, 30, 40]"
    show-size-picker
  />
</template>

Custom Prev/Next Buttons

<template>
  <n-pagination :page-count="101">
    <template #prev>
      Go Prev
    </template>
    <template #next>
      Go Next
    </template>
  </n-pagination>
</template>

With Prefix and Suffix

<template>
  <n-pagination :item-count="101">
    <template #prefix="{ itemCount, startIndex }">
      From Item No.{{ startIndex }}, Total is {{ itemCount }}
    </template>
    <template #suffix="{ endIndex }">
      To Item No.{{ endIndex }}
    </template>
  </n-pagination>
</template>

Different Sizes

<template>
  <n-space vertical>
    <n-pagination
      v-model:page="page"
      :page-count="100"
      size="small"
      show-quick-jumper
      show-size-picker
    />
    <n-pagination
      v-model:page="page"
      :page-count="100"
      size="medium"
      show-quick-jumper
      show-size-picker
    />
    <n-pagination
      v-model:page="page"
      :page-count="100"
      size="large"
      show-quick-jumper
      show-size-picker
    />
  </n-space>
</template>

Custom Page Size Options

<template>
  <n-pagination
    v-model:page="page"
    v-model:page-size="pageSize"
    :page-count="100"
    show-size-picker
    :page-sizes="pageSizes"
  />
</template>

<script setup>
import { ref } from 'vue'

const page = ref(1)
const pageSize = ref(10)
const pageSizes = [
  { label: '10 / page', value: 10 },
  { label: '20 / page', value: 20 },
  { label: '50 / page', value: 50 },
  { label: '100 / page', value: 100 }
]
</script>

Disabled State

<template>
  <n-space vertical>
    <n-pagination
      v-model:page="page"
      v-model:page-size="pageSize"
      :page-count="100"
      show-size-picker
      :page-sizes="[10, 20, 30, 40]"
      show-quick-jumper
      :disabled="disabled"
    />
    <n-switch v-model:value="disabled" />
  </n-space>
</template>

<script setup>
import { ref } from 'vue'

const page = ref(1)
const pageSize = ref(10)
const disabled = ref(false)
</script>

Best Practices

1. Use item-count for dynamic data: When total items change, use item-count instead of page-count

2. Provide page size options: Let users choose how many items to display

3. Show quick jumper for many pages: Enable quick jump when there are many pages

4. Consistent sizing: Match pagination size with other UI elements

5. Handle page changes: Always handle on-update:page and on-update:page-size events

6. Use prefix/suffix for context: Show item range information with prefix/suffix slots