Pagination

Learn about Laravel’s pagination feature. Covers the differences between paginate(), simplePaginate(), and cursorPaginate(); Blade rendering; API responses; and URL customization.

What is pagination

Laravel’s pagination is integrated with the query builder and Eloquent ORM, so you can start using it without any configuration. The current page is automatically detected from the page query parameter on the HTTP request and is also automatically appended to the generated links.

The default HTML supports Tailwind CSS, and Bootstrap CSS is available as an option.

Three pagination methods

Method	Return type	Characteristics
paginate()	LengthAwarePaginator	Fetches total count. Generates numbered page links
simplePaginate()	Paginator	Doesn’t fetch total count. “Previous” and “Next” only
cursorPaginate()	CursorPaginator	Cursor-based. Ideal for large datasets

Basic usage

Query builder pagination

use Illuminate\Support\Facades\DB;

// Retrieve 15 records per page
$users = DB::table('users')->paginate(15);

Eloquent pagination

use App\Models\User;

$users = User::paginate(15);

// With conditions
$users = User::where('votes', '>', 100)->paginate(15);

simplePaginate

When you don’t need a total-count query (displaying only “Previous” and “Next” links), simplePaginate() is more efficient.

$users = DB::table('users')->simplePaginate(15);
$users = User::where('active', true)->simplePaginate(15);

Choose simplePaginate() when you don’t need to display “X of Y total.” paginate() runs an additional COUNT(*) query, so simplePaginate() is faster.

cursorPaginate (cursor pagination)

Cursor pagination uses a WHERE clause instead of OFFSET, delivering high performance on large datasets. It’s especially well-suited to infinite-scroll UIs.

// orderBy is required
$users = DB::table('users')->orderBy('id')->cursorPaginate(15);
$users = User::where('active', true)->cursorPaginate(15);

The generated URLs contain a cursor string instead of a page number.

http://example.com/users?cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0

orderBy is required to use cursor pagination. Also, the sorting columns must belong to the table you’re paginating.

OFFSET vs cursor comparison

-- paginate() / simplePaginate() — uses OFFSET
SELECT * FROM users ORDER BY id ASC LIMIT 15 OFFSET 15;

-- cursorPaginate() — uses WHERE (index-friendly)
SELECT * FROM users WHERE id > 15 ORDER BY id ASC LIMIT 15;

Cursor pagination makes effective use of indexes and is much less likely to duplicate or skip records even when data is frequently added or removed. However, it cannot generate numbered page links—only “Previous” and “Next.”

Controller implementation

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\View\View;

class UserController extends Controller
{
    public function index(): View
    {
        $users = User::orderBy('name')->paginate(20);

        return view('users.index', compact('users'));
    }
}

Displaying pagination links in Blade

<div class="container">
    @foreach ($users as $user)
        <p>{{ $user->name }}</p>
    @endforeach
</div>

{{-- Output pagination links (Tailwind CSS-compatible) --}}
{{ $users->links() }}

The links() method automatically generates HTML for the page links. It shows three pages before and three pages after the current page.

Adjusting the number of visible links

Use onEachSide() to change how many page links to show before and after the current page.

{{-- Display 5 pages on each side of the current page --}}
{{ $users->onEachSide(5)->links() }}

Accepting per-page count from the request

public function index(Request $request): View
{
    $perPage = $request->integer('per_page', 15);
    $perPage = min(max($perPage, 1), 100); // Clamp to 1–100

    $users = User::paginate($perPage);

    return view('users.index', compact('users'));
}

Displaying multiple paginators on one page

When displaying two paginators on the same screen, both using page conflicts. Change the parameter name via the third argument.

$users = User::paginate(
    perPage: 15,
    columns: ['*'],
    pageName: 'users'
);

$posts = Post::paginate(
    perPage: 10,
    columns: ['*'],
    pageName: 'posts'
);

Customizing URLs

Changing the base URL

$users = User::paginate(15);

// Generate URLs in /admin/users?page=N form
$users->withPath('/admin/users');

Appending query parameters

// Add sort=votes to every page link
$users->appends(['sort' => 'votes']);

// Carry over all query parameters from the current request
$users->withQueryString();

Appending a hash fragment

// Add #users to the end of the URL
$users->fragment('users');

API responses (JSON output)

If you return a paginator directly from a route or controller, it’s automatically converted to JSON.

use App\Models\User;

Route::get('/api/users', function () {
    return User::paginate(15);
});

The response’s JSON format:

{
    "total": 50,
    "per_page": 15,
    "current_page": 1,
    "last_page": 4,
    "first_page_url": "http://example.com/api/users?page=1",
    "last_page_url": "http://example.com/api/users?page=4",
    "next_page_url": "http://example.com/api/users?page=2",
    "prev_page_url": null,
    "path": "http://example.com/api/users",
    "from": 1,
    "to": 15,
    "data": [
        { "id": 1, "name": "Taro Yamada" },
        { "id": 2, "name": "Hanako Suzuki" }
    ]
}

Combining with API resources

To wrap a paginate() result with an API resource collection, pass it to UserResource::collection().

use App\Http\Resources\UserResource;
use App\Models\User;

Route::get('/api/users', function () {
    $users = User::paginate(15);

    return UserResource::collection($users);
});

When you pass a paginator to UserResource::collection(), pagination information is automatically added as metadata.

The JSON for cursorPaginate() includes next_cursor and prev_cursor instead of page numbers. API clients use these values as the cursor parameter on the next request.

Custom pagination views

Specifying a view file directly

{{-- Output links with a custom view --}}
{{ $paginator->links('vendor.pagination.custom') }}

{{-- Pass extra data --}}
{{ $paginator->links('vendor.pagination.custom', ['theme' => 'dark']) }}

Changing the default view to a custom file

First publish the official views and then customize.

php artisan vendor:publish --tag=laravel-pagination

The following files are generated in resources/views/vendor/pagination/:

• tailwind.blade.php — Default (for Tailwind CSS)
• bootstrap-5.blade.php — For Bootstrap 5
• simple-tailwind.blade.php — For simplePaginate
• …

Edit tailwind.blade.php directly, or create a new view and specify it in AppServiceProvider.

use Illuminate\Pagination\Paginator;

public function boot(): void
{
    Paginator::defaultView('vendor.pagination.custom');
    Paginator::defaultSimpleView('vendor.pagination.simple-custom');
}

Using Bootstrap CSS

To use Bootstrap instead of Tailwind, configure it in AppServiceProvider’s boot().

use Illuminate\Pagination\Paginator;

public function boot(): void
{
    Paginator::useBootstrapFive(); // Bootstrap 5
    // Paginator::useBootstrapFour(); // Bootstrap 4
}

Manually creating a paginator

To apply pagination to existing data such as an array, instantiate the paginator class directly.

use Illuminate\Pagination\LengthAwarePaginator;

$items = collect(range(1, 200))->map(fn ($i) => ['id' => $i, 'name' => "Item {$i}"]);

$perPage = 15;
$currentPage = request()->integer('page', 1);

$paginator = new LengthAwarePaginator(
    items: $items->forPage($currentPage, $perPage),
    total: $items->count(),
    perPage: $perPage,
    currentPage: $currentPage,
    options: ['path' => request()->url()]
);

Commonly used instance methods

$paginator = User::paginate(15);

$paginator->currentPage();     // Current page number
$paginator->lastPage();        // Last page number (not available on simplePaginate)
$paginator->total();           // Total record count (not available on simplePaginate)
$paginator->perPage();         // Records per page
$paginator->count();           // Records on the current page
$paginator->firstItem();       // Index of the first item on the current page
$paginator->lastItem();        // Index of the last item on the current page
$paginator->hasPages();        // Whether multiple pages exist
$paginator->hasMorePages();    // Whether there's a next page
$paginator->onFirstPage();     // Whether this is the first page
$paginator->onLastPage();      // Whether this is the last page
$paginator->nextPageUrl();     // URL of the next page
$paginator->previousPageUrl(); // URL of the previous page
$paginator->url(3);            // URL of page 3
$paginator->items();           // Array of items on the current page

Summary

How to choose a pagination method

• paginate() — when you need total count and numbered page links (typical list screens)
• simplePaginate() — when “Previous” and “Next” only is sufficient (faster)
• cursorPaginate() — for large datasets, infinite scroll, or when data is written frequently (highest performance)

Basic Blade display pattern

@foreach ($users as $user)
    <p>{{ $user->name }}</p>
@endforeach

{{ $users->links() }}

Just pass the result of paginate() to the view and use links() to output page links. The current page is automatically detected from the page query parameter.

Pagination in APIs

Returning a paginator directly from a route automatically converts it to JSON. To combine with API resources, return UserResource::collection($paginator). The response includes data (an array of records) and various metadata fields.