Pagination

Navigation between pages, with previous and next links.

Installation

Shadwire follows shadcn/ui's open code model: the component's source is copied into your application and becomes yours. Install it with the CLI:

shadwire add pagination --yes

The pagination registry item installs these files:

app/components/ui_component.rb
app/components/ui/pagination_component.rb
app/components/ui/pagination/content_component.rb
app/components/ui/pagination/item_component.rb
app/components/ui/pagination/link_component.rb
app/components/ui/pagination/previous_component.rb
app/components/ui/pagination/next_component.rb
app/components/ui/pagination/ellipsis_component.rb
app/components/ui/button_component.rb
app/components/ui/icon_component.rb
app/helpers/ui/pagination_helper.rb
app/helpers/ui/button_helper.rb
app/helpers/ui/icon_helper.rb
vendor/shadwire/shadwire.css

Haven't installed the CLI yet? gem install shadwire, then shadwire init.

Usage

The links borrow the Button look: the active page uses the outline variant and carries aria-current="page". Wire it to Pagy or Kaminari by generating the real hrefs.

<%= ui_pagination do %>
  <%= ui_pagination_content do %>
    <%= ui_pagination_item do %>
      <%= ui_pagination_previous(href: "?page=1") %>
    <% end %>
    <%= ui_pagination_item do %>
      <%= ui_pagination_link(href: "?page=2", active: true) { "2" } %>
    <% end %>

<%= ui_pagination do %>
  <%= ui_pagination_content do %>
    <%= ui_pagination_item do %>
      <%= ui_pagination_previous(href: "?page=1") %>
    <% end %>
    <%= ui_pagination_item do %>
      <%= ui_pagination_link(href: "?page=2", active: true) { "2" } %>
    <% end %>
    <%= ui_pagination_item do %>
      <%= ui_pagination_next(href: "?page=3") %>
    <% end %>
  <% end %>
<% end %>

Or render the components directly:

<%= render Ui::Pagination::LinkComponent.new(href: "?page=2", active: true) do %>
  2
<% end %>

Composition

Pagination (nav role="navigation" aria-label="pagination")
`-- Pagination::Content (ul)
    |-- Pagination::Item (li) > Pagination::Previous / Pagination::Link / Pagination::Next
    `-- Pagination::Item (li) > Pagination::Ellipsis

Examples

Default

Previous/Next with accessible labels, the active page marked aria-current="page", and a decorative ellipsis.

<%= ui_pagination do %>
  <%= ui_pagination_content do %>
    <%= ui_pagination_item do %>
      <%= ui_pagination_previous(href: "#") %>
    <% end %>
    <%= ui_pagination_item do %>
      <%= ui_pagination_link(href: "#") { "1" } %>
    <% end %>

<%= ui_pagination do %>
  <%= ui_pagination_content do %>
    <%= ui_pagination_item do %>
      <%= ui_pagination_previous(href: "#") %>
    <% end %>
    <%= ui_pagination_item do %>
      <%= ui_pagination_link(href: "#") { "1" } %>
    <% end %>
    <%= ui_pagination_item do %>
      <%= ui_pagination_link(href: "#", active: true) { "2" } %>
    <% end %>
    <%= ui_pagination_item do %>
      <%= ui_pagination_link(href: "#") { "3" } %>
    <% end %>
    <%= ui_pagination_item do %>
      <%= ui_pagination_ellipsis %>
    <% end %>
    <%= ui_pagination_item do %>
      <%= ui_pagination_next(href: "#") %>
    <% end %>
  <% end %>
<% end %>

API reference

Every part accepts class / class_name and **attrs.

Helper	Arguments	Notes
`ui_pagination` / `ui_pagination_content` / `ui_pagination_item`	—	A `nav` landmark, a `ul` list and `li` items.
`ui_pagination_link`	`active: false`, `size: :icon`	Renders an `<a>` styled as a Button (outline when active, ghost otherwise).
`ui_pagination_previous` / `ui_pagination_next`	—	Chevron + label (hidden on small screens); the block replaces the default text.
`ui_pagination_ellipsis`	—	Decorative, with the `sr-only` text "More pages".