Pagination

# Brok UI: Pagination (`pagination`)

Page navigation with previous/next controls, page links, status text, disabled edges, outline/icon-only styles, a page-size slot, and a go-to-page form (GET, or Alpine state with x-page).

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add pagination
```

## Usage

```blade
<x-ui.pagination>
    <x-ui.pagination.content>
        <x-ui.pagination.item>
            <x-ui.pagination.previous href="#" />
        </x-ui.pagination.item>
        <x-ui.pagination.item>
            <x-ui.pagination.link href="#">1</x-ui.pagination.link>
        </x-ui.pagination.item>
        <x-ui.pagination.item>
            <x-ui.pagination.link href="#" :active="true">2</x-ui.pagination.link>
        </x-ui.pagination.item>
        <x-ui.pagination.item>
            <x-ui.pagination.link href="#">3</x-ui.pagination.link>
        </x-ui.pagination.item>
        <x-ui.pagination.item>
            <x-ui.pagination.ellipsis />
        </x-ui.pagination.item>
        <x-ui.pagination.item>
            <x-ui.pagination.link href="#">10</x-ui.pagination.link>
        </x-ui.pagination.item>
        <x-ui.pagination.item>
            <x-ui.pagination.next href="#" />
        </x-ui.pagination.item>
    </x-ui.pagination.content>
</x-ui.pagination>
```

## Props

- `align` (string, default `center`) — Declared by @props in the shipped Blade source.
- `disabled` (false|true, default `false`) — Documented catalog control used by the preview workbench.
- `href` (string, default `#`) — Declared by @props in the registry Blade source.
- `active` (bool, default `false`) — Declared by @props in the registry Blade source.
- `variant` (string, default `ghost`) — Declared by @props in the registry Blade source.
- `showLabel` (bool, default `true`) — Declared by @props in the registry Blade source.
- `label` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `action` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `name` (string, default `page`) — Declared by @props in the registry Blade source.
- `current` (int, default `1`) — Declared by @props in the registry Blade source.
- `total` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `params` (array, default `[]`) — Declared by @props in the registry Blade source.
- `xPage` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `xTotal` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `buttonLabel` (mixed|null, default `null`) — Declared by @props in the registry Blade source.

## Use when

- Use to orient users and help them move across pages, sections, or commands.
- Navigating a long, server- or client-paginated list or table by page number.
- Needing a page-jump form, either a plain GET request or bound to Alpine/Livewire client state.

## Avoid when

- Do not hide primary wayfinding in novelty interactions or deep nested structures if straightforward navigation would be clearer.
- The list is short enough to show in full, or infinite scroll fits the content better than discrete pages.
- Only a simple prev/next flow is needed with no page numbers; a plain button pair is lighter weight.

## Anti-patterns

- Hiding primary wayfinding in novelty interactions

## Rules

- Use the `<brok:pagination>` tag (or `<x-ui.pagination>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/pagination
- Registry JSON (files, props, contract): https://brokui.dev/r/open/pagination.json

@props([
    'href' => '#',
    'active' => false,
    'disabled' => false,
    'variant' => 'ghost',
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    // `ghost` (default) keeps the original look; `outline` gives every page a
    // visible border (Flexnative "outline buttons"). The active page always
    // reads as selected regardless of variant.
    $base = 'inline-flex h-9 min-w-9 items-center justify-center gap-1 rounded-md border px-3 text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none';

    if ($active) {
        $state = 'border-border bg-accent text-accent-foreground';
    } elseif ($variant === 'outline') {
        $state = 'border-input bg-background text-foreground hover:bg-muted';
    } else {
        $state = 'border-transparent text-foreground hover:bg-muted';
    }

    $disabledClasses = $disabled ? ' pointer-events-none opacity-50' : '';

    $classes = trim($base.' '.$state.$disabledClasses);
@endphp

@if ($disabled)
    {{-- A disabled page is non-navigable: render a span, not an anchor, and
         expose the state to assistive tech. --}}
    <span role="link" data-slot="pagination-link" data-variant="{{ $variant }}" data-active="false" aria-disabled="true" {{ $attributes->merge(['class' => $classes]) }}>{{ $slot }}</span>
@else
    <a href="{{ $href }}" data-slot="pagination-link" data-variant="{{ $variant }}" data-active="{{ $active ? 'true' : 'false' }}" @if($active) aria-current="page" @endif {{ $attributes->merge(['class' => $classes]) }}>{{ $slot }}</a>
@endif

@props([
    'href' => '#',
    'disabled' => false,
    'showLabel' => true,
    'label' => null,
])

@php
    $text = $label ?? __('Previous');
    // Icon-only mode keeps a square tap target and an accessible name; the
    // visible word collapses to an sr-only label.
    $padding = $showLabel ? 'ps-2 pe-3' : 'size-9 justify-center';
    $base = 'inline-flex h-9 items-center justify-center gap-1 rounded-md text-sm font-medium text-foreground transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none';
    $classes = trim($base.' '.$padding.($disabled ? ' pointer-events-none opacity-50' : ''));
@endphp

@if ($disabled)
    <span role="link" data-slot="pagination-previous" aria-disabled="true" aria-label="{{ $text }}" {{ $attributes->merge(['class' => $classes]) }}>
        <svg class="size-4 rtl:-scale-x-100" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
            <path d="m15 18-6-6 6-6"></path>
        </svg>
        @if ($showLabel)<span>{{ $text }}</span>@else<span class="sr-only">{{ $text }}</span>@endif
    </span>
@else
    <a href="{{ $href }}" data-slot="pagination-previous" aria-label="{{ $text }}" {{ $attributes->merge(['class' => $classes]) }}>
        <svg class="size-4 rtl:-scale-x-100" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
            <path d="m15 18-6-6 6-6"></path>
        </svg>
        @if ($showLabel)<span>{{ $text }}</span>@else<span class="sr-only">{{ $text }}</span>@endif
    </a>
@endif

@props([
    'href' => '#',
    'disabled' => false,
    'showLabel' => true,
    'label' => null,
])

@php
    $text = $label ?? __('Next');
    // Icon-only mode keeps a square tap target and an accessible name; the
    // visible word collapses to an sr-only label.
    $padding = $showLabel ? 'ps-3 pe-2' : 'size-9 justify-center';
    $base = 'inline-flex h-9 items-center justify-center gap-1 rounded-md text-sm font-medium text-foreground transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none';
    $classes = trim($base.' '.$padding.($disabled ? ' pointer-events-none opacity-50' : ''));
@endphp

@if ($disabled)
    <span role="link" data-slot="pagination-next" aria-disabled="true" aria-label="{{ $text }}" {{ $attributes->merge(['class' => $classes]) }}>
        @if ($showLabel)<span>{{ $text }}</span>@else<span class="sr-only">{{ $text }}</span>@endif
        <svg class="size-4 rtl:-scale-x-100" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
            <path d="m9 18 6-6-6-6"></path>
        </svg>
    </span>
@else
    <a href="{{ $href }}" data-slot="pagination-next" aria-label="{{ $text }}" {{ $attributes->merge(['class' => $classes]) }}>
        @if ($showLabel)<span>{{ $text }}</span>@else<span class="sr-only">{{ $text }}</span>@endif
        <svg class="size-4 rtl:-scale-x-100" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
            <path d="m9 18 6-6-6-6"></path>
        </svg>
    </a>
@endif

@props([
    // Where the form submits (GET). Defaults to the current URL, so `?page=N`
    // lands on Laravel's paginator without extra wiring.
    'action' => null,
    // Query key for the page number.
    'name' => 'page',
    'current' => 1,
    // Last page; leave null when unknown (the input then has no max).
    'total' => null,
    // Extra query params carried along (filters, sort) as hidden inputs.
    'params' => [],
    // Client mode: an Alpine expression holding the page number (`page`,
    // `$wire.page`, `table.page`). The form then never submits: Go (or Enter)
    // clamps the typed number, writes it back and dispatches
    // `pagination:jump` { page }. `xTotal` is the matching last-page expression.
    'xPage' => null,
    'xTotal' => null,
    'label' => null,
    'buttonLabel' => null,
])

@php
    $text = $label ?? __('Go to page');
    $button = $buttonLabel ?? __('Go');
    $id = 'pagination-jump-'.str()->random(6);
    $client = $xPage !== null;
    $maxExpr = $client ? ($xTotal ?? ($total !== null ? (int) $total : 'Infinity')) : null;
    $field = 'inline-flex h-9 w-16 rounded-md border border-input bg-background px-3 text-center text-sm text-foreground shadow-xs transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-[length:var(--ring-width)] focus-visible:ring-ring focus-visible:ring-offset-[length:var(--ring-offset-width)] focus-visible:ring-offset-background motion-reduce:transition-none';
    $submit = 'inline-flex h-9 items-center justify-center rounded-md border border-input bg-background px-3 text-sm font-medium text-foreground shadow-xs transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-[length:var(--ring-width)] focus-visible:ring-ring focus-visible:ring-offset-[length:var(--ring-offset-width)] focus-visible:ring-offset-background motion-reduce:transition-none';
@endphp

{{-- Type a page number and go. Server mode is a plain GET form, so it works
     without JS and with any server-side paginator; client mode (`x-page`)
     keeps the same markup and writes the Alpine state instead. Composes with
     `align="between"`. --}}
<form
    method="get"
    @if ($action !== null) action="{{ $action }}" @endif
    data-slot="pagination-jump"
    data-mode="{{ $client ? 'client' : 'server' }}"
    @if ($client)
        novalidate
        x-data="{ jumpDraft: '' }"
        x-effect="jumpDraft = String({{ $xPage }})"
        @submit.prevent="const max = Number({{ $maxExpr }}) || Infinity; const n = Math.min(Math.max(1, parseInt(jumpDraft, 10) || 1), max); {{ $xPage }} = n; jumpDraft = String(n); $dispatch('pagination:jump', { page: n })"
    @endif
    {{ $attributes->merge(['class' => 'flex items-center gap-2']) }}
>
    @unless ($client)
        @foreach ($params as $key => $value)
            @if ($key !== $name)
                <input type="hidden" name="{{ $key }}" value="{{ $value }}" />
            @endif
        @endforeach
    @endunless
    <label for="{{ $id }}" class="text-sm text-muted-foreground">{{ $text }}</label>
    <input
        id="{{ $id }}"
        type="number"
        name="{{ $name }}"
        inputmode="numeric"
        min="1"
        @if ($client)
            x-model="jumpDraft"
            :max="{{ $maxExpr }} === Infinity ? null : {{ $maxExpr }}"
        @else
            @if ($total !== null) max="{{ (int) $total }}" @endif
            value="{{ (int) $current }}"
        @endif
        required
        class="{{ $field }}"
    />
    @if ($client && $xTotal !== null)
        <span class="text-sm text-muted-foreground" x-text="`{{ __('of :total', ['total' => '${'.$xTotal.'}']) }}`"></span>
    @elseif ($total !== null)
        <span class="text-sm text-muted-foreground">{{ __('of :total', ['total' => (int) $total]) }}</span>
    @endif
    <button type="submit" class="{{ $submit }}">{{ $button }}</button>
</form>