El Pagination

Pagination Component

Pagination component splits large amounts of data into pages for better user experience and performance.

When to Use

• Display large datasets in manageable chunks
• Navigate through search results
• Control page size and current page
• Show total item count and page information

Basic Usage

  

import { ref } from 'vue'

const currentPage = ref(1)
const pageSize = ref(10)
const total = ref(100)

const handleSizeChange = (size) => {
  console.log('Page size:', size)
}

const handleCurrentChange = (page) => {
  console.log('Current page:', page)
}

Layout Configuration

  
  
  
  
  
  
  
  
  , slot"
  >
    Custom content
  

Background Color

Small Size

Pager Count

Hide on Single Page

Custom Icons and Text

  
  
  

import { ArrowLeft, ArrowRight } from '@element-plus/icons-vue'

Complete Example with Data Fetching

  
    
    
  
  
  

import { ref, onMounted } from 'vue'

const tableData = ref([])
const currentPage = ref(1)
const pageSize = ref(10)
const total = ref(0)

const fetchData = async () => {
  const response = await fetch(
    `/api/data?page=${currentPage.value}&size=${pageSize.value}`
  )
  const data = await response.json()
  tableData.value = data.items
  total.value = data.total
}

onMounted(() => {
  fetchData()
})

API Reference

Attributes

| Name | Description | Type | Default | |------|-------------|------|---------| | size | Pagination size | 'large' \| 'default' \| 'small' | 'default' | | background | Buttons have background color | boolean | false | | page-size / v-model:page-size | Items per page | number | — | | default-page-size | Default page size | number | 10 | | total | Total item count | number | — | | page-count | Total page count | number | — | | pager-count | Number of pagers shown | 5 \| 7 \| 9 \| 11 \| 13 \| 15 \| 17 \| 19 \| 21 | 7 | | current-page / v-model:current-page | Current page number | number | — | | default-current-page | Default current page | number | 1 | | layout | Layout elements | string | 'prev, pager, next, jumper, ->, total' | | page-sizes | Options for page size | number[] | [10, 20, 30, 40, 50, 100] | | append-size-to | Element for size dropdown | string | — | | popper-class | Custom class for size dropdown | string | '' | | popper-style | Custom style for size dropdown | string \| object | — | | prev-text | Text for prev button | string | '' | | prev-icon | Icon for prev button | string \| Component | ArrowLeft | | next-text | Text for next button | string | '' | | next-icon | Icon for next button | string \| Component | ArrowRight | | disabled | Disable pagination | boolean | false | | teleported | Teleport dropdown to body | boolean | true | | hide-on-single-page | Hide when only one page | boolean | false |

Layout Elements

| Element | Description | |---------|-------------| | sizes | Page size selector | | prev | Previous page button | | pager | Page number list | | next | Next page button | | jumper | Jump to page input | | -> | Elements after this are pulled right | | total | Total item count display | | slot | Custom slot content |

Events

| Name | Description | Type | |------|-------------|------| | size-change | Page size changed | (value: number) => void | | current-change | Current page changed | (value: number) => void | | change | Page or size changed | (currentPage: number, pageSize: number) => void | | prev-click | Prev button clicked | (value: number) => void | | next-click | Next button clicked | (value: number) => void |

Slots

| Name | Description | |------|-------------| | default | Custom content (requires slot in layout) |

Common Patterns

With v-model Binding

  

import { ref, watch } from 'vue'

const page = ref(1)
const size = ref(10)
const total = ref(100)

watch([page, size], ([newPage, newSize]) => {
  console.log('Page:', newPage, 'Size:', newSize)
})

Responsive Pagination

  

import { ref, onMounted, onUnmounted } from 'vue'

const isMobile = ref(false)
const total = ref(100)

const checkMobile = () => {
  isMobile.value = window.innerWidth  {
  checkMobile()
  window.addEventListener('resize', checkMobile)
})

onUnmounted(() => {
  window.removeEventListener('resize', checkMobile)
})

Custom Slot Content

  
    Page {{ currentPage }}
  

import { ref } from 'vue'

const currentPage = ref(1)

Component Interactions

• Use with Table for paginated data display
• Combine with Select for custom page size options
• Use with Input for custom page jumper
• Integrate with Card for paginated card lists

Best Practices

1. Use v-model:current-page and v-model:page-size for two-way binding
2. Set hide-on-single-page when total items may be small
3. Use background for better visibility on light backgrounds
4. Choose appropriate pager-count based on available width
5. Use size="small" for compact layouts
6. Always define either total or page-count

Deprecation Notes

• small attribute is deprecated, use size="small" instead
• Events are still supported but v-model binding is recommended

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jiaiyan
• Source: jiaiyan/element-plus-skills
• License: MIT
• Homepage: https://skills.sh/jiaiyan/element-plus-skills/element-plus-skills

Install and usage instructions live in the source repository linked above.