Components

Pagination

Headless pagination primitive — page list, edges, and prev/next controls computed from total and page size.

Overview

Pagination is a headless @vyui/core primitive that derives a page range from total and itemsPerPage and exposes the controls to move through it. It ships behavior only — you supply the markup and styling for each page item, ellipsis, and edge control.

This is a layer of @vyui/core — behavior only, no styles.

Anatomy

<PaginationRoot>
  <PaginationList v-slot="{ items }">
    <PaginationFirst />
    <PaginationPrev />
    <template v-for="(item, i) in items" :key="i">
      <PaginationListItem v-if="item.type === 'page'" :value="item.value" />
      <PaginationEllipsis v-else />
    </template>
    <PaginationNext />
    <PaginationLast />
  </PaginationList>
</PaginationRoot>

Usage

<script setup lang="ts">
import {
  PaginationEllipsis,
  PaginationFirst,
  PaginationLast,
  PaginationList,
  PaginationListItem,
  PaginationNext,
  PaginationPrev,
  PaginationRoot,
} from '@vyui/core'

const page = ref(1)
</script>

<template>
  <PaginationRoot
    v-model:page="page"
    :total="120"
    :items-per-page="10"
    :sibling-count="1"
    show-edges
  >
    <PaginationList v-slot="{ items }">
      <PaginationPrev>
        <text>Prev</text>
      </PaginationPrev>
      <template v-for="(item, i) in items" :key="i">
        <PaginationListItem v-if="item.type === 'page'" :value="item.value">
          <text>{{ item.value }}</text>
        </PaginationListItem>
        <PaginationEllipsis v-else>
          <text>…</text>
        </PaginationEllipsis>
      </template>
      <PaginationNext>
        <text>Next</text>
      </PaginationNext>
    </PaginationList>
  </PaginationRoot>
</template>

Features and behavior

page / v-model:page controls the active page; defaultPage seeds uncontrolled state.
itemsPerPage is required; combined with total it computes the number of pages.
siblingCount sets how many page items show on each side of the current page.
showEdges always renders the first page, last page, and ellipses.
disabled blocks interaction with all controls.

API

`PaginationRoot`

Prop	Default	Type
`as`	`"view"`	`AsTag \| Component \| undefined` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`	—	`boolean \| undefined` Change the default rendered element for the one passed as a child, merging their props and behavior. Use this when you need a component to render through a child element while keeping the primitive's props and behavior.
`defaultPage`	`1`	`number \| undefined` The value of the page that should be active when initially rendered. Use when you do not need to control the value state.
`disabled`	—	`boolean \| undefined` When `true`, prevents the user from interacting with item
`itemsPerPage`*	—	`number` Number of items per page
`page`	—	`number \| undefined` The controlled value of the current page. Can be bound as `v-model:page`.
`showEdges`	`false`	`boolean \| undefined` When `true`, always show first page, last page, and ellipsis
`siblingCount`	`2`	`number \| undefined` Number of sibling should be shown around the current page
`total`	`0`	`number \| undefined` Number of items in your list

Event	Payload
`update:page`	`[value: number]`

`PaginationList`

Prop	Default	Type
`as`	—	`AsTag \| Component \| undefined` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`	—	`boolean \| undefined` Change the default rendered element for the one passed as a child, merging their props and behavior. Use this when you need a component to render through a child element while keeping the primitive's props and behavior.

`PaginationListItem`

Prop	Default	Type
`as`	`"view"`	`AsTag \| Component \| undefined` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`	—	`boolean \| undefined` Change the default rendered element for the one passed as a child, merging their props and behavior. Use this when you need a component to render through a child element while keeping the primitive's props and behavior.
`value`*	—	`number` Value for the page

`PaginationPrev` / `PaginationNext`

Prop	Default	Type
`as`	`"view"`	`AsTag \| Component \| undefined` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`	—	`boolean \| undefined` Change the default rendered element for the one passed as a child, merging their props and behavior. Use this when you need a component to render through a child element while keeping the primitive's props and behavior.

Prop	Default	Type
`as`	`"view"`	`AsTag \| Component \| undefined` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`	—	`boolean \| undefined` Change the default rendered element for the one passed as a child, merging their props and behavior. Use this when you need a component to render through a child element while keeping the primitive's props and behavior.

`PaginationFirst` / `PaginationLast`

Prop	Default	Type
`as`	`"view"`	`AsTag \| Component \| undefined` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`	—	`boolean \| undefined` Change the default rendered element for the one passed as a child, merging their props and behavior. Use this when you need a component to render through a child element while keeping the primitive's props and behavior.

Prop	Default	Type
`as`	`"view"`	`AsTag \| Component \| undefined` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`	—	`boolean \| undefined` Change the default rendered element for the one passed as a child, merging their props and behavior. Use this when you need a component to render through a child element while keeping the primitive's props and behavior.

Accessibility

Each control exposes native button semantics; give prev/next/first/last descriptive labels.
The current page item is marked selected so assistive tech announces position.

Tabs — switch between a small fixed set of panels.
FeedList — infinite/virtualized lists instead of discrete pages.

Number Field

Enter, increment, and constrain a numeric value.

Pin Input

Collect a fixed-length numeric or alphanumeric verification code.