Rendering Pagination in Views

will_paginate includes view helpers to render the pagination controls and display information about the current page's entries. These helpers are automatically available in Rails views and can be included in other frameworks like Sinatra and Hanami.

will_paginate

This is the primary helper for rendering the list of pagination links.

Basic Usage

<%= will_paginate @posts %>

This will generate a <div> containing links to other pages, along with "Previous" and "Next" links. The current page will be marked up differently and will not be a link.

If the collection has only one page, this helper returns nil, so nothing is rendered.

Options

The will_paginate helper accepts a hash of options to customize its output:

  • :class: The CSS class for the container <div>. Default is "pagination".
  • :previous_label: The text for the "Previous" link. Default is "&#8592; Previous". Can be configured via I18n.
  • :next_label: The text for the "Next" link. Default is "Next &#8594;". Can be configured via I18n.
  • :inner_window: The number of page links to show on either side of the current page. Default is 4.
  • :outer_window: The number of page links to show at the beginning and end of the list. Default is 1.
  • :link_separator: The string to use between page links. Default is a single space (' ').
  • :param_name: The name of the query parameter for the page number. Default is :page.
  • :params: A hash of additional query parameters to include in the generated URLs.
  • :renderer: A class or instance of a custom link renderer for full control over the HTML output. (See Customization guide).
  • :container: A boolean to toggle the rendering of the container <div>. Set to false if you want to provide your own wrapper element. Default is true.

Any other options passed will be rendered as HTML attributes on the container <div>.

Example with Options

<%= will_paginate @posts, 
      inner_window: 2, 
      outer_window: 0, 
      previous_label: '<<', 
      next_label: '>>', 
      params: { controller: 'posts', action: 'index' } %>

page_entries_info

This helper displays a summary of the entries shown on the current page.

Usage

<%= page_entries_info @posts %>

Output Examples

  • For a collection with multiple pages: "Displaying posts <b>11&nbsp;-&nbsp;20</b> of <b>55</b> in total"
  • For a single-page collection with multiple items: "Displaying <b>all&nbsp;5</b> posts"
  • For an empty collection: "No posts found"

Options

  • :model: A string or model class to be used for the entry name (e.g., 'posts' or Post). If not provided, will_paginate will attempt to infer it from the collection.
  • :html: A boolean that toggles HTML output (like <b> tags). Default is true.

paginated_section (Rails only)

This is a convenience helper that renders pagination links both above and below a block of content.

Usage

<%= paginated_section @posts do %>
  <ol id="posts-list">
    <% @posts.each do |post| %>
      <li><%= post.title %></li>
    <% end %>
  </ol>
<% end %>

This will output:

<div class="pagination">...</div>
<ol id="posts-list">...</ol>
<div class="pagination">...</div>