Skip to content
Bladewell

<x-widget.pagination>

Pagination Blade component for Laravel and Livewire

Paginator links in seven styles: drawer (bottom sheet of pages), numbers, segmented numbers, jump-to-page, table footer with rows per page, a summary with previous/next, and load more. In a Livewire component (WithPagination) every style changes page in place.

php artisan bladewell:add pagination
Also adds
Button, Icon, Modal
Used by
Table
Works with
Laravel 12 and 13, Livewire 3 and 4, Tailwind CSS 4.1+, PHP 8.3+

Usage

Livewire component

In a Livewire component, use WithPagination: every style's page links (and the jump form and the page sheet) then call gotoPage() on the component, in place, instead of reloading the page, and the URL follows. For rows per page (type="footer") or load more, add a property and name it with per-page-model. Every public property can be set from the browser, so check the page size before it reaches the query.

PHP
use Livewire\Attributes\Url;
use Livewire\Component;
use Livewire\WithPagination;

class Orders extends Component
{
    use WithPagination;

    #[Url]
    public string $search = '';

    // per-page-model="perPage": the footer's select sets it; load more raises it by a page each time.
    public int $perPage = 10;

    public function updatedSearch(): void
    {
        $this->resetPage();
    }

    public function render()
    {
        return view('livewire.orders', [
            'orders' => auth()->user()->orders()
                // % and _ typed match themselves, the same on every database (ESCAPE '!'), and LOWER() ignores case.
                ->when($this->search, fn ($query) => $query->whereRaw("LOWER(number) LIKE LOWER(?) ESCAPE '!'", ['%'.str_replace(['!', '%', '_'], ['!!', '!%', '!_'], mb_substr($this->search, 0, 100)).'%']))
                ->latest()
                ->paginate(min(max($this->perPage, 1), 100)),
        ]);
    }
}

Livewire view

The view for that component. Any style works as it is; per-page-model is only needed for rows per page and load more. Give each item a wire:key.

Blade
<div>
    <input type="search" wire:model.live.debounce.300ms="search" placeholder="Search orders" aria-label="Search orders">

    <ul id="orders">
        @foreach ($orders as $order)
            <li wire:key="order-{{ $order->id }}">{{ $order->number }}</li>
        @endforeach
    </ul>

    {{-- Pick one. --}}
    <x-widget.pagination type="numbers" :paginator="$orders" />
    <x-widget.pagination type="footer" :paginator="$orders" per-page-model="perPage" :per-page-options="[10, 25, 50]" />
    <x-widget.pagination type="load-more" :paginator="$orders" target="#orders" per-page-model="perPage" />
</div>

On the server

Here's how to keep the pagination's requests cheap on your server.

Server cost

Examples

Drawer

The default. Tapping the current page opens a bottom sheet listing every page, built only when it first opens. Pass any paginator, e.g. Order::query()->paginate(10) from your controller.

Pass $orders from your controller.

Show code
Blade
<x-widget.pagination :paginator="$orders" />

Numbers

First, last, the current page and its neighbours, with gaps shown as an ellipsis. Pass any paginator, e.g. Order::query()->paginate(10) from your controller.

Pass $orders from your controller.

Show code
Blade
<x-widget.pagination type="numbers" :paginator="$orders" />

Segmented

The numbers style as one joined, bordered group with the current page filled. A boxier look for admin screens. Pass any paginator, e.g. Order::query()->paginate(10) from your controller.

Pass $orders from your controller.

Show code
Blade
<x-widget.pagination type="segmented" :paginator="$orders" />

Jump

Previous and next, plus a field to go straight to a page. Suits very long lists. Pass any paginator, e.g. Order::query()->paginate(10) from your controller.

Pass $orders from your controller.

Show code
Blade
<x-widget.pagination type="jump" :paginator="$orders" />

Summary

"Showing 11 to 20 of 470 results" with labelled Previous and Next buttons. Clear at any width, and works with simplePaginate() too (the total is left out). Pass any paginator, e.g. Order::query()->paginate(10) from your controller.

Pass $orders from your controller.

Show code
Blade
<x-widget.pagination type="summary" :paginator="$orders" />

Load more

Appends the next page to the list in place, without leaving the page. target is the list's selector, and each item must be a direct child of it. Without JavaScript it's a link to the next page. Works with paginate(), simplePaginate() and cursorPaginate(); pass e.g. Order::query()->latest()->paginate(5) from your controller. In a Livewire component, add per-page-model="perPage": the component then renders the longer list itself (see Usage).

Pass $orders from your controller.

  • ORD-1099 $56.00
  • ORD-1098 $93.00
  • ORD-1097 $130.00
  • ORD-1096 $167.00
  • ORD-1095 $204.00

Showing 5 of 23

Show code
Blade
<div class="w-full max-w-md">
    <ul id="order-list" class="bg-surface border-line divide-line divide-y rounded-xl border">
        @foreach ($orders as $order)
            <li class="flex items-center justify-between px-4 py-3 text-sm">
                <span class="font-medium">{{ $order['number'] }}</span>
                <span class="text-foreground/75 tabular-nums">{{ $order['total'] }}</span>
            </li>
        @endforeach
    </ul>

    <x-widget.pagination type="load-more" :paginator="$orders" target="#order-list" />
</div>

Props

Other attributes, such as autocomplete or data-*, are passed through to the element. class styles the component's outer wrapper.

<x-widget.pagination>

Prop Default Description
paginator Required Any Laravel paginator: paginate(), simplePaginate() or cursorPaginate() (the last two get the summary style, or load more, since they have no page count). In Livewire, from a component using WithPagination.
type 'drawer' drawer (a bottom sheet of pages), numbers, segmented, jump, footer (with rows per page), summary or load-more.
per-page-options [10, 25, 50, 100] type="footer": the sizes to offer. Declared here so they reach it: forwarded attributes keep kebab-case names.
per-page-name 'per_page' type="footer": the query parameter the size submits as.
per-page-model null Livewire: the rows-per-page property, e.g. "perPage". type="footer" binds its select to it; type="load-more" raises it by a page each time, so the component renders the longer list.

<x-widget.pagination.drawer>

Prop Default Description
paginator Required A length-aware paginator (paginate()).

<x-widget.pagination.footer>

Prop Default Description
paginator Required A length-aware paginator (paginate()).
per-page-options [10, 25, 50, 100] The sizes to offer; the current one is always offered too.
per-page-name 'per_page' The query parameter the size submits as; your controller reads it (and checks it against its own list).
per-page-model null Livewire: the component property for rows per page, e.g. "perPage". Changing it updates in place and goes back to page 1 (resetPage, from WithPagination), as the form does without Livewire.

<x-widget.pagination.jump>

Prop Default Description
paginator Required A length-aware paginator (paginate()).

<x-widget.pagination.load-more>

Prop Default Description
paginator Required Any Laravel paginator; with cursorPaginate() it loads just as fast on page 500 as on page 2.
target Required CSS selector for the list the items are rendered in, e.g. "#order-list". New items are appended to it.
label 'Load more' The button's text.
per-page-model null Livewire: the rows-per-page property to raise by a page each time (e.g. "perPage"), so the component renders the longer list; appended items would be gone at its next render. Without it, the button moves to the next page.

<x-widget.pagination.numbers>

Prop Default Description
paginator Required A length-aware paginator (paginate()).
segmented false The pages as one joined, bordered group with the current page filled, instead of separate links.

<x-widget.pagination.summary>

Prop Default Description
paginator Required Any Laravel paginator; a cursor paginator gets the buttons without the item numbers.

Accessibility

All 7 examples above are checked with axe-core against the WCAG 2.2 A and AA rules, in the light theme and the dark one, both as the page draws and with each popover, dialog, toast and tooltip opened, on every change. A change that fails can't be merged. Where axe can't decide, such as contrast on SVG text, the test measures the colours itself instead of letting it pass.

Automated checks can't judge everything: how it sounds in a screen reader, and how it feels to use from the keyboard, still need a person. Check those on your own pages too.

Source

What bladewell:add pagination writes to your app with the default namespaces. Prefer to copy by hand? Take these files, plus the ones from the components it also adds , and the theme and base CSS.

resources/views/components/widget/pagination/drawer.blade.php Show
drawer.blade.php
resources/views/components/widget/pagination/footer.blade.php Show
footer.blade.php
resources/views/components/widget/pagination/index.blade.php Show
index.blade.php
resources/views/components/widget/pagination/jump.blade.php Show
jump.blade.php
resources/views/components/widget/pagination/load-more.blade.php Show
load-more.blade.php
resources/views/components/widget/pagination/numbers.blade.php Show
numbers.blade.php
resources/views/components/widget/pagination/summary.blade.php Show
summary.blade.php
resources/js/widget/pagination/index.js Show
index.js
app/View/Widget/ElementIds.php Show
ElementIds.php