11 · Navigation

Pagination

shape canvas · rounded · pill × size sm/md/lg · count and items per page

Pagination for lists and tables.

Turning the page

1 2 3 4 … 44
.heex
<.pagination loop page={0} total_pages={44} page_attrs={fn p -> if p == :ellipsis or p > 4, do: %{style: "--dl:0s"}, else: %{style: "--dl:#{:erlang.float_to_binary((p - 1) * 1.5, decimals: 1)}s"} end} />

shape × size

smmdlgcanvas
1 2 3 4 … 44
1 2 3 4 … 44
1 2 3 4 … 44
rounded
1 2 3 4 … 44
1 2 3 4 … 44
1 2 3 4 … 44
pill
1 2 3 4 … 44
1 2 3 4 … 44
1 2 3 4 … 44
.heex
<div class="grid grid-cols-[90px_repeat(3,_minmax(0,1fr))] gap-y-[10px] gap-x-[12px] items-center"><span></span><span class="text-xs text-muted font-mono text-center">sm</span><span class="text-xs text-muted font-mono text-center">md</span><span class="text-xs text-muted font-mono text-center">lg</span><span class="text-xs text-muted font-mono">canvas</span><div class="flex justify-center min-w-0"><.pagination page={2} total_pages={44} shape="canvas" size="sm" page_attrs={fn p -> if p == :ellipsis or p > 4, do: %{style: "--dl:0s"}, else: %{style: "--dl:#{:erlang.float_to_binary((p - 1) * 1.5, decimals: 1)}s"} end} /></div><div class="flex justify-center min-w-0"><.pagination page={2} total_pages={44} shape="canvas" size="md" page_attrs={fn p -> if p == :ellipsis or p > 4, do: %{style: "--dl:0s"}, else: %{style: "--dl:#{:erlang.float_to_binary((p - 1) * 1.5, decimals: 1)}s"} end} /></div><div class="flex justify-center min-w-0"><.pagination page={2} total_pages={44} shape="canvas" size="lg" page_attrs={fn p -> if p == :ellipsis or p > 4, do: %{style: "--dl:0s"}, else: %{style: "--dl:#{:erlang.float_to_binary((p - 1) * 1.5, decimals: 1)}s"} end} /></div><span class="text-xs text-muted font-mono">rounded</span><div class="flex justify-center min-w-0"><.pagination page={2} total_pages={44} shape="rounded" size="sm" page_attrs={fn p -> if p == :ellipsis or p > 4, do: %{style: "--dl:0s"}, else: %{style: "--dl:#{:erlang.float_to_binary((p - 1) * 1.5, decimals: 1)}s"} end} /></div><div class="flex justify-center min-w-0"><.pagination page={2} total_pages={44} shape="rounded" size="md" page_attrs={fn p -> if p == :ellipsis or p > 4, do: %{style: "--dl:0s"}, else: %{style: "--dl:#{:erlang.float_to_binary((p - 1) * 1.5, decimals: 1)}s"} end} /></div><div class="flex justify-center min-w-0"><.pagination page={2} total_pages={44} shape="rounded" size="lg" page_attrs={fn p -> if p == :ellipsis or p > 4, do: %{style: "--dl:0s"}, else: %{style: "--dl:#{:erlang.float_to_binary((p - 1) * 1.5, decimals: 1)}s"} end} /></div><span class="text-xs text-muted font-mono">pill</span><div class="flex justify-center min-w-0"><.pagination page={2} total_pages={44} shape="pill" size="sm" page_attrs={fn p -> if p == :ellipsis or p > 4, do: %{style: "--dl:0s"}, else: %{style: "--dl:#{:erlang.float_to_binary((p - 1) * 1.5, decimals: 1)}s"} end} /></div><div class="flex justify-center min-w-0"><.pagination page={2} total_pages={44} shape="pill" size="md" page_attrs={fn p -> if p == :ellipsis or p > 4, do: %{style: "--dl:0s"}, else: %{style: "--dl:#{:erlang.float_to_binary((p - 1) * 1.5, decimals: 1)}s"} end} /></div><div class="flex justify-center min-w-0"><.pagination page={2} total_pages={44} shape="pill" size="lg" page_attrs={fn p -> if p == :ellipsis or p > 4, do: %{style: "--dl:0s"}, else: %{style: "--dl:#{:erlang.float_to_binary((p - 1) * 1.5, decimals: 1)}s"} end} /></div></div>

Usage

<.pagination page={@page} total_pages={44} />

Rules

  • Current page with a ring and an xs shadow (same logic as the segmented control).
  • Show “1–25 of 1,096” on the left.

API reference

Todos os function components, atributos, valores e slots que este componente cobre.

Pagination: the canvas pager (shape canvas, rounded or pill) or the classic bar of buttons (shape="classic"), in three sizes. Styled only with Tailwind utilities; every part carries data-part (pagination, pagination-page, pagination-arrow, pagination-ellipsis, pagination-footer, pagination-summary, pagination-size...).

<.pagination page={@page} total_pages={10} patch={&"/orders?page=#{&1}"} />
<.pagination page={@page} total_pages={10} on_change="paginate" shape="pill" />

Each page is a link when patch, navigate or href is given (a function from the page number to a path); otherwise a button pushing on_change with %{"page" => "3"} (to target). With neither, the pager is display-only (plain spans). Pages far from the current one collapse into …: siblings pages on each side of the current one and boundaries at each end.

A list footer: total_entries and page_size add the "Showing 1–15 of 128" summary (and work out total_pages), page_sizes a rows-per-page select in its own <form> pushing on_page_size with %{"page_size" => "30"}. With a summary, a select or an :aside the root is a lu-row around the pages.

The canvas shapes style > span, so interactive pages are spans holding the button or link. summary defaults to "Showing %{first}–%{last} of %{total}" when total_entries is given; an explicit summary is shown as-is without it. Accessibility, rendered server-side: the current page carries aria-current="page" (on the link/button, or on the span when the pager is display-only), every page and arrow has an aria-label (page_label, prev_label, next_label), the summary is role="status". shape="classic" is an addition to the README.

<.pagination>

Attr Type Default Values / notes
page (required) :integer
total_pages :integer nil
total_entries :integer nil
page_size :integer nil
page_sizes :list []
on_page_size :any nil
summary :string nil
page_size_label :string "%{size} / page"
page_size_aria :string "Rows per page"
siblings :integer 1
boundaries :integer 1
patch :any nil
navigate :any nil
href :any nil
on_change :any nil
target :any nil
divided :boolean false
loop :boolean false The animated mock: pages 1-4 take the current look in turn (give page={0}).
shape :string "canvas" canvas, rounded, pill, classic
variant :string nil nil, canvas, rounded, pill, classic - The same as shape; it wins when given.
size :string "md" sm, md, lg
arrows :boolean true
arrows_at :string "end" end, sides - Where the arrows go in the canvas pager: end (the bundle: both after the pages) or sides (previous before the pages, next after them, as in the classic bar).
prev_label :string "Previous page"
next_label :string "Next page"
page_label :string "Page %{page}"
page_attrs :any nil Function from a page number (or :ellipsis) to extra attrs (%{style: ..., class: ...}) of its item, e.g. for staggered animations.
class :any nil

Any other HTML/phx attribute goes to the root element.

Slots:

  • <:aside>