Skip to content
Destyler Destyler Destyler
Docs
Pagination

Pagination

Pagination is an interface that allows navigating between pages that contain split information, instead of being shown on a single page.

Features

Install

Install the component from your command line.

Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/pagination @destyler/vue
Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/pagination @destyler/react
Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/pagination @destyler/svelte
Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/pagination @destyler/solid

Anatomy

Import all parts and piece them together.

<script setup lang="ts">
import * as pagination from '@destyler/pagination'
import { normalizeProps, useMachine } from '@destyler/vue'
import { computed, useId } from 'vue'


const [state, send] = useMachine(pagination.machine({
  id: useId(),
  count: 1000
}))


const api = computed(() => pagination.connect(state.value, send, normalizeProps))
</script>


<template>
  <nav v-bind="api.getRootProps()">
    <ul>
      <li>
        <a v-bind="api.getPrevTriggerProps()"></a>
      </li>
      <li v-for="(page, i) in api.pages" :key="page.type === 'page' ? page.value : `ellipsis-${i}`">
        <span v-if="page.type === 'page'">
          <a v-bind="api.getItemProps(page)" ></a>
        </span>
        <span v-else>
          <span v-bind="api.getEllipsisProps({ index: i })" ></span>
        </span>
      </li>
      <li>
        <a v-bind="api.getNextTriggerProps()"></a>
      </li>
    </ul>
  </nav>
</template>
import * as pagination from '@destyler/pagination'
import { normalizeProps, useMachine } from '@destyler/react'
import { useId } from 'react'


export default function Pagination() {
  const [state, send] = useMachine(pagination.machine({
    id: useId(),
    count: 1000,
  }))


  const api = pagination.connect(state, send, normalizeProps)


  return (
    <nav {...api.getRootProps()}>
      <ul>
        <li>
          <a {...api.getPrevTriggerProps()}></a>
        </li>
        {api.pages.map((page, i) => (
          <li key={page.type === 'page' ? page.value : `ellipsis-${i}`}>
            {page.type === 'page'
            ? (
              <a {...api.getItemProps(page)}></a>
            )
            : (
              <span {...api.getEllipsisProps({ index: i })}></span>
            )}
          </li>
        ))}
        <li>
          <a {...api.getNextTriggerProps()}></a>
        </li>
      </ul>
    </nav>
  )
}
<script lang="ts">
  import * as pagination from '@destyler/pagination'
  import { normalizeProps, useMachine } from '@destyler/svelte'


  const id = $props.id()


  const [state, send] = useMachine(pagination.machine({ id, count: 1000 }))


  const api = $derived(pagination.connect(state, send, normalizeProps))
</script>


<nav {...api.getRootProps()}>
  <ul>
    <li>
      <a {...api.getPrevTriggerProps()}></a>
    </li>
    {#each api.pages as page, i}
      <li>
        {#if page.type === 'page'}
          <a {...api.getItemProps(page)}></a>
        {:else}
          <span {...api.getEllipsisProps({ index: i })}></span>
        {/if}
      </li>
    {/each}
    <li>
      <a {...api.getNextTriggerProps()}></a>
    </li>
  </ul>
</nav>
import * as pagination from '@destyler/pagination'
import { normalizeProps, useMachine } from '@destyler/solid'
import { createMemo, createUniqueId } from 'solid-js'


export default function Pagination() {
  const [state, send] = useMachine(pagination.machine({
    id: createUniqueId(),
    count: 1000,
  }))


  const api = createMemo(() => pagination.connect(state, send, normalizeProps))


  return (
    <nav {...api().getRootProps()}>
      <ul>
        <li>
          <a {...api().getPrevTriggerProps()}></a>
        </li>
        {api().pages.map((page, i) => (
          <li>
            {page.type === 'page'
              ? (
                  <a {...api().getItemProps(page)}></a>
                )
              : (
                  <span {...api().getEllipsisProps({ index: i })}></span>
                )}
          </li>
        ))}
        <li>
          <a {...api().getNextTriggerProps()}></a>
        </li>
      </ul>
    </nav>
  )
}

Controlled usage

Pagination supports controllable page and pageSize. Prefer defaultPage / defaultPageSize for uncontrolled seeds. Passing page / pageSize into machine(...) is presence-controlled — sync with onPageChange / onPageSizeChange and adapter context. See Controllable State.

pagination.machine({
  id: "1",
  count: 100,
  defaultPage: 1,
  defaultPageSize: 10,
})


const page = 1 // your reactive state
pagination.machine({
  id: "1",
  count: 100,
  page,
  onPageChange(details) {
    // details => { page: number, pageSize: number }
  },
})

Styling Guide

Earlier, we mentioned that each collapse part has a data-part attribute added to them to select and style them in the DOM.

[data-part="root"] {
  /* styles for the pagination's root */
}


[data-part="item"] {
  /* styles for the pagination's items */
}


[data-part="ellipsis"] {
  /* styles for the pagination's ellipsis */
}


[data-part="prev-trigger"] {
  /* styles for the pagination's previous page trigger */
}


[data-part="next-trigger"] {
  /* styles for the pagination's next page trigger */
}


/* We add a data-disabled attribute to the prev/next items when on the first/last page  */


[data-part="prev-trigger"][data-disabled] {
  /* styles for the pagination's previous page trigger when on first page */
}


[data-part="next-trigger"][data-disabled] {
  /* styles for the pagination's next page trigger when on first page */
}

Methods and Properties

Machine Context

The pagination machine exposes the following context properties:

ids
Partial<{ root: string; ellipsis: (index: number) => string; prevTrigger: string; nextTrigger: string; item: (page: number) => string; }>
The ids of the elements in the accordion. Useful for composition.
translations
IntlTranslations
Specifies the localized strings that identifies the accessibility elements and their states
count
number
Total number of data items
pageSize(default: 10)
number
Number of data items per page (controlled sync field)
defaultPageSize
number
The initial page size when it is not controlled. Prefer this over seeding with `pageSize` for uncontrolled usage.
siblingCount(default: 1)
number
Number of pages to show beside active page
page(default: 1)
number
The controlled active page
defaultPage
number
The initial active page when it is not controlled. Prefer this over seeding with `page` for uncontrolled usage.
onPageChange
(details: PageChangeDetails) => void
Called when the page number is changed
onPageSizeChange
(details: PageSizeChangeDetails) => void
Called when the page size is changed
type(default: "button")
"button" | "link"
The type of the trigger element
dir(default: "ltr")
"ltr" | "rtl"
The document's text/writing direction.
id
string
The unique identifier of the machine.
getRootNode
() => ShadowRoot | Node | Document
A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.

Machine API

The pagination api exposes the following methods:

page
number
The current page.
count
number
The total number of data items.
pageSize
number
The number of data items per page.
totalPages
number
The total number of pages.
pages
Pages
The page range. Represented as an array of page numbers (including ellipsis)
previousPage
number
The previous page.
nextPage
number
The next page.
pageRange
PageRange
The page range. Represented as an object with `start` and `end` properties.
slice
<V>(data: V[]) => V[]
Function to slice an array of data based on the current page.
setCount
(count: number) => void
Function to set the total number of pages.
setPageSize
(size: number) => void
Function to set the page size.
setPage
(page: number) => void
Function to set the current page.
goToNextPage
() => void
Function to go to the next page.
goToPrevPage
() => void
Function to go to the previous page.
goToFirstPage
() => void
Function to go to the first page.
goToLastPage
() => void
Function to go to the last page.

Data Attributes

Item

attribute
description
data-scope
pagination
data-part
item
data-index
The index of the item
data-selected
Present when selected

Prev Trigger

attribute
description
data-scope
pagination
data-part
prev-trigger
data-disabled
Present when disabled

Next Trigger

attribute
description
data-scope
pagination
data-part
next-trigger
data-disabled
Present when disabled

Navigation Menu

Popover