# Pagination

Numbered pagination with prev/next buttons, ellipses, and configurable siblings.

- Package: `@mielui/svelte`
- Component version: `1.0.0`
- Depends on Mielui components: _internal/utils
- Shared utilities: hugeicons-icon, utils.cn, utils.pressable

## Install

~~~~sh
pnpm dlx @mielui/svelte add pagination
~~~~

## API

This reference is generated at build time from the component manifest, public `index.ts`, and documentation examples below. Changes to those source files are reflected here in the published Markdown. Standard Svelte and HTML attributes accepted by the exported prop types are supported.


### Pagination

| Prop | Type | Default | Required | Bindable | Description |
| --- | --- | --- | --- | --- | --- |
| labels | PaginationLabels \| undefined | - | No | No | Overrides the built-in text and accessible names. Every key is optional and English is the fallback. |
| page | number \| undefined | 1 | No | Yes | Current page, starting at 1. Bindable. |
| total | number | - | Yes | No | Number of pages. |
| siblings | number \| undefined | 1 | No | No | Page links shown on each side of the current page. |
| onPageChange | ((page: number) => void) \| undefined | - | No | No | Called with the new page. |
| class | string \| undefined | - | No | No | Classes added to the element. |
| children | Snippet<[]> \| undefined | - | No | No | Content rendered inside. |



### Public types

~~~~ts
import type { DefaultProps } from '@mielui/svelte/utils';
import Pagination from './pagination.svelte';

export type PaginationLabels = {
    /** Accessible name of the navigation landmark. */
    navigation?: string;
    /** Accessible name of the previous-page button. */
    previous?: string;
    /** Accessible name of the next-page button. */
    next?: string;
    /** Accessible name of a page button. Without it, the page number names the button. */
    page?: (page: number) => string;
};

export type PaginationProps = {
    /**
     * Overrides the built-in text and accessible names. Every key is optional and English is the
     * fallback.
     */
    labels?: PaginationLabels;
    /** Current page, starting at 1. Bindable. */
    page?: number;
    /** Number of pages. */
    total: number;
    /** Page links shown on each side of the current page. */
    siblings?: number;
    /** Called with the new page. */
    onPageChange?: (page: number) => void;
} & DefaultProps;

export { Pagination };
export default Pagination;
~~~~

## Examples

### Hero

~~~~svelte
<script lang="ts">
    import { numberShuffle } from '@mielui/svelte/actions/number-shuffle';
    import { Pagination } from '@mielui/svelte/components/pagination';

    const pageSize = 5;
    const items = Array.from({ length: 48 }, (_, index) => {
        return {
            number: `INV-${1001 + index}`,
            amount: `$${((index * 37) % 90) * 10 + 120}.00`
        };
    });
    const totalPages = Math.ceil(items.length / pageSize);

    let page = $state(1);

    const pageItems = $derived(items.slice((page - 1) * pageSize, page * pageSize));
</script>

<div class="flex w-full max-w-sm flex-col gap-4">
    <ul class="m-0 flex list-none flex-col divide-y divide-border p-0">
        {#each pageItems as item (item.number)}
            <li class="flex items-center justify-between py-2 text-sm text-foreground">
                <span>{item.number}</span>
                <span class="text-foreground-muted tabular-nums">{item.amount}</span>
            </li>
        {/each}
    </ul>
    <div class="flex flex-col items-start justify-between gap-3 sm:flex-row sm:items-center">
        <p class="m-0 text-xs text-foreground-muted tabular-nums">
            {'Page '}
            <span use:numberShuffle={{ value: page }}>{page}</span>
            {' of '}
            <span use:numberShuffle={{ value: totalPages }}>{totalPages}</span>
        </p>
        <Pagination bind:page total={totalPages} />
    </div>
</div>
~~~~

### Siblings

~~~~svelte
<script lang="ts">
    import { Pagination } from '@mielui/svelte/components/pagination';

    let page = $state(8);
</script>

<div class="flex justify-center p-2 sm:p-6">
    <Pagination bind:page total={20} siblings={2} />
</div>
~~~~

For the rendered reference, visit [/docs/components/pagination](/docs/components/pagination).