Pagination

Project a large result set into direct pages and boundary controls.

Usage

Compact

Use a reduced control set when horizontal space is limited.

<!-- Pagination / Compact -->
<script setup lang="ts">
import { PaginationRoot, PaginationFirst, PaginationPrevious, PaginationItem, PaginationNext, PaginationLast } from '@sectile/vue/pagination'
</script>

<template>
  <PaginationRoot :total="240" :default-items-per-page="20" v-slot="{ items }">
    <PaginationFirst>First</PaginationFirst>
    <PaginationPrevious>Previous</PaginationPrevious>
    <template v-for="item in items.filter(item => item.type !== 'control')" :key="JSON.stringify(item)">
      <span v-if="item.type === 'ellipsis'" aria-hidden="true">…</span>
      <PaginationItem v-else :item="item">{{ item.page }}</PaginationItem>
    </template>
    <PaginationNext>Next</PaginationNext>
    <PaginationLast>Last</PaginationLast>
  </PaginationRoot>
</template>

Page size

Change the number of items per page and return to the first valid page when necessary.

<!-- Pagination / Page Size -->
<script setup lang="ts">
import { PaginationRoot, PaginationFirst, PaginationPrevious, PaginationItem, PaginationNext, PaginationLast } from '@sectile/vue/pagination'
</script>

<template>
  <PaginationRoot :total="240" :default-items-per-page="20" v-slot="{ items }">
    <PaginationFirst>First</PaginationFirst>
    <PaginationPrevious>Previous</PaginationPrevious>
    <template v-for="item in items.filter(item => item.type !== 'control')" :key="JSON.stringify(item)">
      <span v-if="item.type === 'ellipsis'" aria-hidden="true">…</span>
      <PaginationItem v-else :item="item">{{ item.page }}</PaginationItem>
    </template>
    <PaginationNext>Next</PaginationNext>
    <PaginationLast>Last</PaginationLast>
  </PaginationRoot>
</template>

Pages only

Render direct page choices without first and last controls.

<!-- Pagination / Pages Only -->
<script setup lang="ts">
import { PaginationRoot, PaginationFirst, PaginationPrevious, PaginationItem, PaginationNext, PaginationLast } from '@sectile/vue/pagination'
</script>

<template>
  <PaginationRoot :total="240" :default-items-per-page="20" v-slot="{ items }">
    <PaginationFirst>First</PaginationFirst>
    <PaginationPrevious>Previous</PaginationPrevious>
    <template v-for="item in items.filter(item => item.type !== 'control')" :key="JSON.stringify(item)">
      <span v-if="item.type === 'ellipsis'" aria-hidden="true">…</span>
      <PaginationItem v-else :item="item">{{ item.page }}</PaginationItem>
    </template>
    <PaginationNext>Next</PaginationNext>
    <PaginationLast>Last</PaginationLast>
  </PaginationRoot>
</template>

Controlled

Let the parent own the current value and apply accepted changes back to the component.

<!-- Pagination / Controlled -->
<script setup lang="ts">
import { PaginationRoot, PaginationFirst, PaginationPrevious, PaginationItem, PaginationNext, PaginationLast } from '@sectile/vue/pagination'
</script>

<template>
  <PaginationRoot :total="240" :default-items-per-page="20" v-slot="{ items }">
    <PaginationFirst>First</PaginationFirst>
    <PaginationPrevious>Previous</PaginationPrevious>
    <template v-for="item in items.filter(item => item.type !== 'control')" :key="JSON.stringify(item)">
      <span v-if="item.type === 'ellipsis'" aria-hidden="true">…</span>
      <PaginationItem v-else :item="item">{{ item.page }}</PaginationItem>
    </template>
    <PaginationNext>Next</PaginationNext>
    <PaginationLast>Last</PaginationLast>
  </PaginationRoot>
</template>

Examples

Long range

Navigate a large result set without rendering every page number.

<!-- Pagination / Long Range -->
<script setup lang="ts">
import { PaginationRoot, PaginationFirst, PaginationPrevious, PaginationItem, PaginationNext, PaginationLast } from '@sectile/vue/pagination'
</script>

<template>
  <PaginationRoot :total="240" :default-items-per-page="20" v-slot="{ items }">
    <PaginationFirst>First</PaginationFirst>
    <PaginationPrevious>Previous</PaginationPrevious>
    <template v-for="item in items.filter(item => item.type !== 'control')" :key="JSON.stringify(item)">
      <span v-if="item.type === 'ellipsis'" aria-hidden="true">…</span>
      <PaginationItem v-else :item="item">{{ item.page }}</PaginationItem>
    </template>
    <PaginationNext>Next</PaginationNext>
    <PaginationLast>Last</PaginationLast>
  </PaginationRoot>
</template>

API

Vue package: @sectile/vue/pagination

Components

PaginationRoot
PaginationItem
PaginationFirst
PaginationPrevious
PaginationNext
PaginationLast

Props

`PaginationRootProps`

as: TypePrimitiveAsDefault'nav'
Element or component rendered for this part.
asChild: TypebooleanDefaultfalse
Whether to merge this part into its single child instead of rendering a wrapper.
defaultItemsPerPage: TypenumberDefault10
Initial uncontrolled number of records shown per page.
defaultValue: TypenumberDefault1
Initial value used when the component owns its state.
disabled: TypebooleanDefaultfalse
Whether interaction is unavailable.
getControlLabel: Type(control: PaginationControl) => stringDefaultundefined
Returns the accessible label announced for a pagination control.
getPageLabel: Type(page: number) => stringDefaultundefined
Returns the accessible label announced for a page choice.
itemsPerPage: TypenumberDefaultundefined
Controlled number of records shown per page.
label: TypestringDefault'Pagination'
Accessible name announced for the control.
modelValue: TypenumberDefaultundefined
Current value when state is controlled by the parent.
readonly: TypebooleanDefaultfalse
Whether the value can be inspected but not changed.
showControls: TypebooleanDefaulttrue
Whether first, previous, next, and last controls are included.
showEdges: TypebooleanDefaulttrue
Whether the first and last page numbers remain visible.
siblingCount: TypenumberDefault1
Number of adjacent page choices shown around the current page.
total: TypenumberDefaultRequired
Total number of records represented by pagination.

`PaginationItemProps`

as: TypePrimitiveAsDefault'button'
Element or component rendered for this part.
asChild: TypebooleanDefaultfalse
Whether to merge this part into its single child instead of rendering a wrapper.
item: TypePaginationViewItemDefaultRequired
Pagination item rendered by this part.

Slots

`PaginationRootSlotProps`

items: Typereadonly PaginationViewItem[]
Current derived item collection.
itemsPerPage: Typenumber
Number of records currently shown per page.
page: Typenumber
Current one-based page number.
pageCount: Typenumber
Total number of available pages.
range: TypePaginationItemRange
Current start and end values.

`PaginationItemSlotProps`

disabled: Typeboolean
Whether interaction is unavailable.
item: TypePaginationViewItem
Current pagination item.
selected: Typeboolean
Whether this item is selected.

Events

`PaginationRoot`

update:itemsPerPage: Payloadnumber
Emitted when the requested page size changes.
update:modelValue: Payloadnumber
Emitted when the component requests a new controlled value.

Other types

`PaginationPageLabelResolver`

type PaginationPageLabelResolver = NonNullable<PaginationRootProps['getPageLabel']>

`PaginationControlLabelResolver`

type PaginationControlLabelResolver = NonNullable<PaginationRootProps['getControlLabel']>

`PaginationValueChangeHandler`

type PaginationValueChangeHandler = (value: number) => void

`PaginationItemsPerPageChangeHandler`

type PaginationItemsPerPageChangeHandler = (value: number) => void

Parts

Shared scope: [data-scope="pagination"]. Combine it with a part selector to keep styles local to this component.

Part	Selector	Role	Extra attributes
`root`	`[data-part="root"]`	Defines the component boundary and owns its composed parts.	—
`first`	`[data-part="first"]`	Moves to the first page.	—
`previous`	`[data-part="previous"]`	Moves to the previous item or page.	—
`item`	`[data-part="item"]`	Represents one selectable or actionable item.	—
`next`	`[data-part="next"]`	Moves to the next item or page.	—
`last`	`[data-part="last"]`	Moves to the last page.	—

Keyboard interaction

Key	Behavior
`Tab`	Move between pagination controls exposed as native buttons or links.
`Enter` / `Space`	Activate the focused page or boundary control.
`Home` / `End`	The terminal projection moves to the first or last page.

Accessibility

Page links or buttons keep native activation semantics and identify the current page without relying on position alone.

Pagination ​

Usage ​

Compact ​

Page size ​

Pages only ​

Controlled ​

Examples ​

Long range ​

API ​

Props ​

PaginationRootProps ​

PaginationItemProps ​

Slots ​

PaginationRootSlotProps ​

PaginationItemSlotProps ​

Events ​

PaginationRoot ​

Other types ​

PaginationPageLabelResolver ​

PaginationControlLabelResolver ​

PaginationValueChangeHandler ​

PaginationItemsPerPageChangeHandler ​

Parts ​

Keyboard interaction ​

Accessibility ​