<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
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.
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.
<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
-
If people can choose rows per page, cap it on the server (
min(100, …)); the menu's choices don't limit what the query string can ask for.Laravel: Pagination · OWASP API4: Unrestricted resource consumption
-
Consider
simplePaginate()for the summary and load-more styles, which show no page count: it skips thecount(*)query. For deep or endless lists,cursorPaginate()stays as fast on page 500 as on page 1.
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 Hide code
<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 Hide code
<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 Hide code
<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 Hide code
<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 Hide code
<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
Load moreShow code Hide code
<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
resources/views/components/widget/pagination/footer.blade.php Show
resources/views/components/widget/pagination/index.blade.php Show
resources/views/components/widget/pagination/jump.blade.php Show
resources/views/components/widget/pagination/load-more.blade.php Show
resources/views/components/widget/pagination/numbers.blade.php Show
resources/views/components/widget/pagination/summary.blade.php Show
resources/js/widget/pagination/index.js Show
app/View/Widget/ElementIds.php Show