Pagination

Accessible page navigation with explicit boundaries, current state, and ellipses.

Source: app/components/nitro_kit/pagination.rb
API: NitroKit::Pagination.new(label:, pagy: nil) { |pagination| pagination.page; pagination.ellipsis }

Boundary states

First, middle, and last pages expose one current item and disabled outer boundaries.

First, middle, last

First page

Middle page

Last page

Viewport640 px · sm

Width

Preset

Rubytest/dummy/app/components/gallery/components/pagination_page.rb

Gallery::Data.pagination_boundaries.each do |pagination|
  sample(pagination.label, slug: pagination.slug) do
    render_boundary(pagination)
  end
end

Pagy

A real Pagy object supplies previous, series, gap, current, and next items through its public API. The application still owns the query and the route.

First, middle, and last Pagy pages

First page

Middle page

Last page

ViewportFull width

Width

Preset

Rubytest/dummy/app/components/gallery/components/pagination_page.rb

[ [ "First page", 1 ], [ "Middle page", 6 ], [ "Last page", 12 ] ].each do |label, page|
  sample(label, slug: "pagination-pagy-#{page}") do
    render NitroKit::Pagination.new(
      pagy: gallery_pagy(page),
      id: "gallery-pagination-pagy-#{page}",
      label: "#{label} of workspace records"
    )
  end
end

Ranges and ellipses

Compact and long ranges use non-interactive, accessibly labelled ellipses.

Compact range

Viewport640 px · sm

Width

Preset

Rubytest/dummy/app/components/gallery/components/pagination_page.rb

render NitroKit::Pagination.new(
  id: "gallery-pagination-compact",
  label: "Compact result pages"
) do |pagination|
  pagination.prev(href: "/gallery/results?page=1", id: "gallery-pagination-compact-previous")
  pagination.page(1, href: "/gallery/results?page=1", id: "gallery-pagination-compact-page-1")
  pagination.page(2, current: true, id: "gallery-pagination-compact-page-2")
  pagination.page(3, href: "/gallery/results?page=3", id: "gallery-pagination-compact-page-3")
  pagination.next(href: "/gallery/results?page=3", id: "gallery-pagination-compact-next")
end

Long range

ViewportFull width

Width

Preset

Rubytest/dummy/app/components/gallery/components/pagination_page.rb

render NitroKit::Pagination.new(
  id: "gallery-pagination-long",
  label: "Long audit log pages"
) do |pagination|
  pagination.prev(href: "/gallery/audit?page=6", id: "gallery-pagination-long-previous")
  pagination.page(1, href: "/gallery/audit?page=1", id: "gallery-pagination-long-page-1")
  pagination.ellipsis(label: "Pages 2 through 5 omitted")
  pagination.page(6, href: "/gallery/audit?page=6", id: "gallery-pagination-long-page-6")
  pagination.page(7, current: true, id: "gallery-pagination-long-page-7")
  pagination.page(8, href: "/gallery/audit?page=8", id: "gallery-pagination-long-page-8")
  pagination.ellipsis(label: "Pages 9 through 23 omitted")
  pagination.page(24, href: "/gallery/audit?page=24", id: "gallery-pagination-long-page-24")
  pagination.next(href: "/gallery/audit?page=8", id: "gallery-pagination-long-next")
end

Labels and pressure

Long navigation copy, block page labels, icon-only boundaries, and wide ranges remain semantic.

Long labels

ViewportFull width

Width

Preset

Rubytest/dummy/app/components/gallery/components/pagination_page.rb

render NitroKit::Pagination.new(
  id: "gallery-pagination-labels",
  label: "Archived audit record pages"
) do |pagination|
  pagination.prev(
    "Back to newer archived records",
    href: "/gallery/archive?page=4",
    icon: nil,
    id: "gallery-pagination-labels-previous"
  )
  pagination.page(href: "/gallery/archive?page=5", id: "gallery-pagination-labels-page") do
    "A custom page label"
  end
  pagination.next(
    "Continue to older archived records",
    href: "/gallery/archive?page=6",
    icon: nil,
    id: "gallery-pagination-labels-next"
  )
end

Horizontal pressure

ViewportFull width

Width

Preset

Rubytest/dummy/app/components/gallery/components/pagination_page.rb

render NitroKit::Pagination.new(
  id: "gallery-pagination-pressure",
  label: "Twelve visible pages"
) do |pagination|
  pagination.prev(href: "/gallery/pressure?page=5", id: "gallery-pagination-pressure-previous")
  (1..12).each do |page|
    pagination.page(
      page,
      href: "/gallery/pressure?page=#{page}",
      current: page == 6,
      id: "gallery-pagination-pressure-page-#{page}"
    )
  end
  pagination.next(href: "/gallery/pressure?page=7", id: "gallery-pagination-pressure-next")
end

Paginated results

Field, Input, Table, Badge, Button, and Pagination compose into searchable member results.

Member search

Search members

Three of 128 matching members
Name	Role	Status
Ada Lovelace	Owner	Active
Grace Hopper	Admin	Active
Katherine Johnson	Member	Invited

ViewportFull width

Width

Preset

Rubytest/dummy/app/components/gallery/components/pagination_page.rb

render NitroKit::Field.new(
  nil,
  :query,
  as: :search,
  id: "gallery-pagination-search",
  name: "search[query]",
  value: "engineering",
  label: "Search members",
  placeholder: "Name or email",
  html: { id: "gallery-pagination-search-field" }
)

render NitroKit::Table.new(
  id: "gallery-pagination-results-table",
  table_html: { id: "gallery-pagination-results-table-element" }
) do |table|
  table.caption("Three of 128 matching members")
  table.thead do
    table.tr do
      table.th("Name")
      table.th("Role")
      table.th("Status", align: :right)
    end
  end
  table.tbody do
    Gallery::Data.members.each do |member|
      table.tr do
        table.th(member.name, scope: :row)
        table.td(member.role.to_s.humanize)
        table.td(align: :right) do
          render NitroKit::Badge.new(
            member.status.to_s.humanize,
            id: "gallery-pagination-result-status-#{member.id}",
            color: member_status_color(member.status),
            size: :sm
          )
        end
      end
    end
  end
end

render NitroKit::Pagination.new(
  id: "gallery-pagination-results",
  label: "Member search result pages"
) do |pagination|
  pagination.prev(id: "gallery-pagination-results-previous")
  pagination.page(1, current: true, id: "gallery-pagination-results-page-1")
  pagination.page(2, href: "/gallery/members?query=engineering&page=2", id: "gallery-pagination-results-page-2")
  pagination.ellipsis(label: "Pages 3 through 15 omitted")
  pagination.page(16, href: "/gallery/members?query=engineering&page=16", id: "gallery-pagination-results-page-16")
  pagination.next(
    href: "/gallery/members?query=engineering&page=2",
    id: "gallery-pagination-results-next"
  )
end

Component contract

Constructor options, rendered root, closed vocabularies, and compound boundary for this component, exactly as shipped.

docs/component_contracts.md · NitroKit::Pagination

Constructor-specific options: label: defaulting to I18n.t("nitro_kit.pagination.label"), pagy: nil, page_url: nil, id: nil
Root and closed vocabulary: nav[data-nk=pagination]
Compound contract: Accepts either a declaration block or a Pagy object. A Pagy object builds previous, series, gap, current, and next items automatically through Pagy's public previous, next, data_hash, and page_url API; a callable page_url: overrides those destinations. prev and next fall back to their default labels only when no content block supplies one. The current page without an href renders span[data-slot=pagination-current][aria-current=page], not a Button. Manual items retain ordering, uniqueness, current-link, and ellipsis validation. Default previous/next text, their fallback aria-labels, and the ellipsis label come from nitro_kit.pagination.*.

Relevant patterns

Application conventions this component belongs to. Each summary is the leading section of its pattern document.

docs/patterns/queryable_collection.md

Queryable collection

One GET-driven Turbo Frame owns filters, sorting, results, and pagination; URL parameters are the state.
An application query object owns allowlists, defaults, tenant scope, and page bounds; NitroKit::Table owns no query policy.
Pagination advances browser history; filters, reset, and sorting replace the current history entry.
Every response contains the same frame, including empty results; links that leave the collection target _top.

System rules for coding agents

Instructions for coding agents, repeated on every component page so one fetched page has enough context. Humans can usually skip this section.

test/dummy/app/components/gallery/agent_rules.rb

View agent instructions

Nitro Kit 2.0 is a gem-owned, Phlex-only UI system for Rails. Render components directly: render NitroKit::Button.new("Save", variant: :primary).
Compose Nitro components inside application-owned Phlex classes. Public initializers and declared slots are the component API; private methods are not.
Public options are explicit keywords, and enumerated options are closed vocabularies. Invalid names or values raise ArgumentError; this component's accepted options are in the contract above.
Pass native attributes through their typed boundary: html: for HTML, aria: for ARIA, and data: for application data. class and style are forbidden, including inside html:.
Nitro owns NitroKit::Component::RESERVED_DATA_ATTRIBUTES: data-nk, data-slot, data-variant, data-size, data-nk-escape, data-enhanced, data-state, data-disabled, data-required, data-orientation, data-presentation, data-placement, data-layout, data-side, data-field-type, data-dir, data-gap, data-align, data-justify, data-wrap, data-cols, data-mode, data-key. Do not pass them through data:. data-action, data-controller are additive and compose with Nitro behavior.
If an integration truly requires a class, use desperately_need_a_class:. It requires a non-blank String and marks the exception with data-nk-escape="class".
Every root emits data-nk; owned parts emit component-qualified data-slot values such as field-control or card-title. Select on those attributes, never on classes.
Customize components with documented --nk-* custom properties in an application stylesheet. Variables beginning with --_nk-* are private component mechanics.
Use NitroKit::Flex and NitroKit::Grid for layout. Parents own external placement and available width; components own their intrinsic geometry.
Preserve native elements and accessibility semantics. State is exposed through native semantics and ARIA first, and through data-state when styling or behavior also needs it.