Skip to content

Pagination

David Ciulla edited this page Nov 7, 2026 · 1 revision

Pagination

Laravex provides offset-based and simplified pagination through Laravex.Database.Model and Laravex.Http.Paginator. The API mirrors Laravel's paginate / simplePaginate conventions.

Introduction

Both paginator types return a pager map that contains the data, metadata, and a precomputed links HTML string. In Blade templates, render the links with the @links or {{{ pager.links }}} helper.

Length-Aware Pagination (paginate)

Runs a COUNT(*) first, then fetches the page — giving you a last-page number and full page number windows:

# 15 results per page, page 1
pager = App.Models.Post.paginate(15, page, path: "/posts")

The pager map contains:

Key Type Description
data list Model structs for the current page
total integer Total row count
per_page integer Rows per page
current_page integer Current page number
last_page integer ceil(total / per_page)
path string Base URL for page links
query map Extra query params preserved in links
links string Precomputed HTML navigation
simple false Marks this as a full paginator

Simple Pagination (simple_paginate)

Avoids the COUNT(*) query — faster for large tables. Fetches one extra row to know if a "next" page exists:

pager = App.Models.Post.simple_paginate(15, page, path: "/posts")
Key Type Description
data list Model structs for the current page
has_more_pages boolean Whether a next page exists
current_page integer Current page
per_page integer Rows per page
simple true Marks this as a simple paginator

Rendering Links in Blade

The links key contains prebuilt HTML. In a Blade template:

{{{ pager.links }}}

Or call the paginator directly with a custom path:

html = Laravex.Http.Paginator.links(pager, "/admin/posts")

The full paginator renders a window of page numbers with ellipsis:

<nav class="pagination">
  <span class="disabled">&laquo; Previous</span>
  <span class="current">1</span>
  <a href="/posts?page=2">2</a>
  <span class="ellipsis">&hellip;</span>
  <a href="/posts?page=10">10</a>
  <a href="/posts?page=2">Next &raquo;</a>
</nav>

The simple paginator renders only Previous / Next links:

<nav class="pagination">
  <span class="disabled">&laquo; Previous</span>
  <a href="/posts?page=2">Next &raquo;</a>
</nav>

Generating Page URLs

# Build ?page=N URL preserving existing query string params
Laravex.Http.Paginator.page_url(pager, 3)
# => "/posts?page=3"

Laravex.Http.Paginator.page_url(pager, 3, "/articles")
# => "/articles?page=3"

Extra query params already in pager.query are merged in automatically (the page key is stripped before merging).

Page Window Elements

Paginator.elements/3 returns the list of page numbers and :ellipsis atoms used to build the navigation window:

Laravex.Http.Paginator.elements(5, 20)
# => [1, :ellipsis, 3, 4, 5, 6, 7, :ellipsis, 20]

The window shows on_each_side pages around the current page (default 2).

Reading the Current Page from the Request

Extract the page number from request params in a controller:

def index(request) do
  page = String.to_integer(Map.get(request.params, "page", "1"))
  pager = App.Models.Post.paginate(15, page, path: "/posts")
  Laravex.View.make("posts/index", %{pager: pager})
end

JSON Responses

Pass a pager to Laravex.Http.Response.json_paginated/2 to get a standard JSON envelope:

App.Http.Resources.PostResource.paginated(pager)

This applies your JSON resource transformer to each row (via collection/1) and wraps the result in the response envelope.

See Also

  • Query-Builder — Low-level chunk/3 and chunk_by_id/3 for large-table processing
  • Eloquex — Model.paginate/3 and Model.simple_paginate/3
  • Eloquex-Resources — JSON Resource wrappers for paginated API responses

Clone this wiki locally