Phoenix implementation of Zag.js Pagination.

Pagination and Carousel both use 1-based page (first page is 1). Page numbers and ellipses are rendered on the server so the control is complete before the hook runs.

Anatomy

Minimal

<.pagination class="pagination" count={95} page_size={10}>
  <:prev><.heroicon name="hero-chevron-left" /></:prev>
  <:next><.heroicon name="hero-chevron-right" /></:next>
  <:ellipsis><.heroicon name="hero-ellipsis-horizontal" /></:ellipsis>
</.pagination>

Controlled page

<.pagination
  class="pagination"
  count={18}
  page={@page}
  page_size={4}
  controlled
  on_page_change="pagination_controlled_changed"
>
  <:prev><.heroicon name="hero-chevron-left" /></:prev>
  <:next><.heroicon name="hero-chevron-right" /></:next>
  <:ellipsis><.heroicon name="hero-ellipsis-horizontal" /></:ellipsis>
</.pagination>

def mount(_params, _session, socket) do
  {:ok, assign(socket, :page, 1)}
end

def handle_event("pagination_controlled_changed", %{"page" => page}, socket) do
  {:noreply, assign(socket, :page, page)}
end

Link mode

Set type={:link}, to, and optional page_param / page_size_param. The hook builds href on each control (SSR and client).

For assigns-driven state, prefer type={:button}, controlled, and on_page_change instead of link mode.

Translation

<.pagination
  class="pagination"
  count={95}
  page_size={10}
  translation={%Corex.Pagination.Translation{
    prev_trigger_label: Corex.Gettext.gettext("Previous page"),
    next_trigger_label: Corex.Gettext.gettext("Next page"),
    item_label:
      Corex.Gettext.gettext("Page %{page} of %{total_pages}",
        page: "%{page}",
        total_pages: "%{total_pages}"
      )
  }}
>
  <:prev><.heroicon name="hero-chevron-left" /></:prev>
  <:next><.heroicon name="hero-chevron-right" /></:next>
  <:ellipsis><.heroicon name="hero-ellipsis-horizontal" /></:ellipsis>
</.pagination>

API

Requires a stable id on <.pagination>.

set_page

<.action phx-click={Corex.Pagination.set_page("pagination-api-bind", 5)} class="button button--sm">5</.action>
<.pagination id="pagination-api-bind" class="pagination" count={95} page={5} page_size={10}>
  <:prev><.heroicon name="hero-chevron-left" /></:prev>
  <:next><.heroicon name="hero-chevron-right" /></:next>
  <:ellipsis><.heroicon name="hero-ellipsis-horizontal" /></:ellipsis>
</.pagination>

def handle_event("pagination_api_page_3", _, socket) do
  {:noreply, Corex.Pagination.set_page(socket, "pagination-api-srv", 3)}
end

Events

Pick an event name and pass it to on_* on <.pagination>.

Server events

on_page_change

<.pagination class="pagination" count={95} page_size={10} on_page_change="pagination_page_changed">
  <:prev><.heroicon name="hero-chevron-left" /></:prev>
  <:next><.heroicon name="hero-chevron-right" /></:next>
  <:ellipsis><.heroicon name="hero-ellipsis-horizontal" /></:ellipsis>
</.pagination>

def handle_event("pagination_page_changed", %{"id" => id, "page" => page}, socket) do
  {:noreply, assign(socket, :page, page)}
end

Client events

on_page_change_client

<.pagination
  id="pagination-events-client"
  class="pagination"
  count={95}
  page_size={10}
  on_page_change_client="pagination-page-changed"
>
  <:prev><.heroicon name="hero-chevron-left" /></:prev>
  <:next><.heroicon name="hero-chevron-right" /></:next>
  <:ellipsis><.heroicon name="hero-ellipsis-horizontal" /></:ellipsis>
</.pagination>

document.getElementById("pagination-events-client")?.addEventListener("pagination-page-changed", (e) => {
  console.log(e.detail);
});

Patterns

Controlled

Bind page (and optionally page_size) with controlled (true, :all, :page, or :page_size) and handle on_page_change so assigns stay the source of truth.

<.pagination
  class="pagination"
  count={18}
  page={@page}
  page_size={4}
  controlled
  on_page_change="pagination_controlled_changed"
>
  <:prev><.heroicon name="hero-chevron-left" /></:prev>
  <:next><.heroicon name="hero-chevron-right" /></:next>
  <:ellipsis><.heroicon name="hero-ellipsis-horizontal" /></:ellipsis>
</.pagination>

Slice list data on the server (Zag api.slice is client-only):

offset = (page - 1) * page_size
Enum.slice(items, offset, page_size)

Patch (URL)

Use type={:link}, controlled, to, and redirect={:patch} so page and page size sync from query params via handle_params/3.

<.pagination
  class="pagination"
  count={18}
  page={@page}
  page_size={4}
  controlled={:all}
  type={:link}
  to="/posts"
  redirect={:patch}
>
  <:prev><.heroicon name="hero-chevron-left" /></:prev>
  <:next><.heroicon name="hero-chevron-right" /></:next>
  <:ellipsis><.heroicon name="hero-ellipsis-horizontal" /></:ellipsis>
</.pagination>

Style

Target parts with data-scope and data-part, or import pagination.css and stack modifiers on the host.

[data-scope="pagination"][data-part="root"] {}
[data-scope="pagination"][data-part="item"] {}
[data-scope="pagination"][data-part="ellipsis"] {}
[data-scope="pagination"][data-part="prev-trigger"][data-disabled] {}
[data-scope="pagination"][data-part="next-trigger"][data-disabled] {}

@import "../corex/main.css";
@import "../corex/tokens/themes/neo/light.css";
@import "../corex/components/pagination.css";

Stack modifiers on <.pagination class="pagination ...">.

Color

Size

Text

Rounded

Max width