Pagination

Overview

The Pagination component is a core building block of the Byteion design system, providing a robust, accessibility-compliant interface for its specific UI capabilities.

Why this exists

Pagination enables navigation through large datasets. It communicates the total volume of data and the user's current position within it.

Mental model

When to use

When not to use

Basic example

The following example demonstrates standard usage, fully compliant with Byteion's token-first approach.

import { useState } from 'react';
import { Pagination } from '@byteion/react';

export default function PaginationDemo() {
  const [page, setPage] = useState(3);
  return (
    <div className="space-y-6 p-6">
      <Pagination page={page} totalPages={10} onPageChange={setPage} />
      <Pagination page={1}    totalPages={5}  onPageChange={() => {}} variant="compact" />
    </div>
  );
}

<script setup lang="ts">
import { ref } from 'vue';
import { Pagination } from '@byteion/vue';

const page = ref(3);
</script>

<template>
  <div class="space-y-6 p-6">
    <Pagination v-model="page" :total-pages="10" />
    <Pagination :model-value="1" :total-pages="5" variant="compact" />
  </div>
</template>

States

This component reacts seamlessly to the following interaction and data states:

• default — Resting appearance before interaction.
• active — Currently selected or in use.
• disabled — Non-interactive — grayed out, cursor not-allowed.
• hover — Pointer is over the element — visual feedback via color or shadow.
• focus — Keyboard or tab focus — shows ring indicator for accessibility.

Anatomy

Usage guidelines

• Show 5-7 page numbers at most.
• Always show prev/next.
• Include a per-page selector for large datasets.

Do and Don't

Accessibility

Uses <nav aria-label="Pagination">. Current page has aria-current="page". Prev/Next have descriptive labels.

Customization

Active page color follows --primary.

import { cva, cn, type VariantProps } from '@byteion/react';

const myPagination = cva('base classes…', {
 variants: {
  accent: { soft:'border-primary-200', loud:'border-primary-500' },
 },
 defaultVariants: { accent:'soft' },
});

type Props = React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof myPagination>;

<script setup lang="ts">
import { computed, useAttrs } from 'vue';
import { cva, type VariantProps } from '@byteion/vue';

interface Props { accent?:'soft' |'loud' }
const props = withDefaults(defineProps<Props>(), { accent:'soft' });
const attrs = useAttrs();

const myPagination = cva('base classes…', {
  variants: { accent: { soft:'border-primary-200', loud:'border-primary-500' } },
});

const cls = computed(() => myPagination({ accent: props.accent, class: attrs.class as string | undefined }));
</script>

Runtime events

Byteion keeps framework APIs idiomatic: HTML uses DOM custom events, React uses callback props, and Vue uses emitted events / v-model updates.

Remote / AJAX

API Reference

Static HTML. Page changes trigger navigation or API call.

export interface PaginationProps extends Omit<HTMLAttributes<HTMLElement>, 'onChange'> {
  /** Current 1-based page number. */
  page: number;
  /** Total number of pages. */
  totalPages: number;
  /** Called with the new page number. */
  onPageChange: (page: number) => void;
  /** Visual layout. */
  variant?: 'numbered' | 'prev-next' | 'compact';
  /** Max number of page buttons shown in the numbered variant. Default 5. */
  siblings?: number;
  /** Accessible label for the nav element. */
  'aria-label'?: string;
}

export interface PaginationProps {
  /** Current 1-based page number. */
  page: number;
  /** Total number of pages. */
  totalPages: number;
  /** Visual layout. */
  variant?: 'numbered' | 'prev-next' | 'compact';
  /** Max number of page buttons shown in the numbered variant. Default 5. */
  siblings?: number;
  /** Accessible label for the nav element. */
  ariaLabel?: string;
}

Developer tips

Common mistakes

Production usage tips

Premium examples

Advanced patterns available in Byteion Pro:

Related components

• Table
• Data Table
• Breadcrumb
• Button
• Select
• Skeleton
• Empty state