usePagination

Creates reusable pagination primitives without assuming how data is loaded. Use it when multiple components need the same page, page-size, total, and limits behavior, whether data is sliced locally or fetched from a server.

The composable keeps state deliberately simple: setters only assign values and do not clamp pages, reset page numbers, or trigger side effects. That makes it predictable, but callers should handle validation when needed.

Importing

import { usePagination } from '@almighty-shogun/common'

Usage

import { watch } from 'vue'
import { usePagination } from '@almighty-shogun/common'

const { page, perPage, setPage, setPerPage, setTotal } = usePagination(25);

watch([page, perPage], async () => {
    const response = await fetch('/api/users?page=' + page.value + '&limit=' + perPage.value);
    const result = await response.json();

    setTotal(result.total);
});

setPage(2);
setPerPage(50);

Parameters

pageSize: number
Initial perPage value.
Default: 5

Returns

limits: Ref<number[]>
Available page-size options: [5, 10, 25, 50, 100].

page: Ref<number>
One-based current page. Starts at 1.

perPage: Ref<number>
Current page size. Starts with pageSize.

total: Ref<number>
Total number of items across all pages. Starts at 0.

setTotal(total: number): void
Updates total item count.

setPage(page: number): void
Updates the active page.

setPerPage(perPage: number): void
Updates the active page size.

Type signature

declare function usePagination(pageSize: number): UsePagination;

type UsePagination = {
    readonly limits: Ref<number[]>;
    readonly page: Ref<number>;
    readonly perPage: Ref<number>;
    readonly total: Ref<number>;

    setTotal(total: number): void;
    setPage(page: number): void;
    setPerPage(perPage: number): void;
};