use-offset-pagination

Offset-based pagination state.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useOffsetPagination } from "@vizejs/composable/use-offset-pagination";

Try it

Browse a guide catalogue

Slice a local list into pages with previous/next boundaries and a writable page-size selector.

Open the interactive example

What to observe: Go to the last page, then change Guides per page to five. The page is clamped to the new last page and the visible list changes. Previous and Next disable at the boundaries.

currentPage is one-based; offset is zero-based. currentPageSize can be used with v-model.number. The composable manages state; the example's computed ref slices the data.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { computed, useId } from "vue";
import { useOffsetPagination } from "@vizejs/composable/use-offset-pagination";

const guides = [
  "Setup",
  "Components",
  "Composables",
  "Styling",
  "Accessibility",
  "Testing",
  "Deployment",
];
const sizeId = useId();
const { currentPage, currentPageSize, pageCount, offset, isFirstPage, isLastPage, prev, next } =
  useOffsetPagination({ total: guides.length, pageSize: 3 });
const visibleGuides = computed(() =>
  guides.slice(offset.value, offset.value + currentPageSize.value),
);
</script>

<template>
  <div class="composable-example">
    <label :for="sizeId">Guides per page</label>
    <select :id="sizeId" v-model.number="currentPageSize">
      <option :value="3">3</option>
      <option :value="5">5</option>
    </select>
    <ul aria-label="Guides on this page">
      <li v-for="guide in visibleGuides" :key="guide">{{ guide }}</li>
    </ul>
    <div class="example-actions">
      <button type="button" :disabled="isFirstPage" @click="prev">Previous page</button>
      <output aria-live="polite">Page {{ currentPage }} of {{ pageCount }}</output>
      <button type="button" :disabled="isLastPage" @click="next">Next page</button>
    </div>
  </div>
</template>

Runtime contract

API

useOffsetPagination

Offset-based pagination state. The page is clamped into [1, pageCount] on every read and write, so shrinking total or growing pageSize never leaves the cursor past the end. Writable page/pageSize refs are updated in place for two-way binding. Callbacks fire after the corresponding value settles. Synchronous state: SSR-safe; watchers follow the owning scope.

function useOffsetPagination(options: UseOffsetPaginationOptions = {}): OffsetPagination

const { currentPage, pageCount, next, offset } = useOffsetPagination({ total, pageSize: 20 });

Types

OffsetPaginationInfo

Page information passed to the useOffsetPagination callbacks.

UseOffsetPaginationOptions

Options for useOffsetPagination.

OffsetPagination

Pagination state and controls returned by useOffsetPagination.