n-pagination

Pagination component for navigating through data pages. Invoke when user needs to implement pagination, page navigation, or data pagination controls in Naive UI.

SKILL.md

GitHub

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 number undefined Current page (controlled).
prefix (info) => VNodeChild undefined Prefix render function.
scrollbar-props ScrollbarProps undefined Scrollbar props. 2.44.0
select-props SelectProps undefined Page size select props. 2.34.3
show-quick-jumper boolean false Whether to show quick jump input.
show-quick-jump-dropdown boolean true Whether to show quick jump dropdown. 2.37.0
size 'small' | 'medium' | 'large' 'medium' Size of page item. 2.29.0
simple boolean false Whether to use simple mode. 2.32.2
suffix (info) => VNodeChild undefined Suffix render function.
show-size-picker boolean false Whether to show size picker.
to string | HTMLElement | false 'body' Container node of pop menu. 2.33.4
on-update:page (page) => void undefined Callback when page changes.
on-update:page-size (pageSize) => void undefined Callback when page size changes.

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