Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP


tigrish edited this page · 4 revisions

will_paginate documentation

This is the official home for will_paginate library; a collection of extensions for the database layer that enable paginated queries, and view helpers for popular frameworks that render pagination links. With proper combination of view helpers and CSS styling, the final result can look like this:

will_paginate sample rendering

To get started, see Installation instructions.

Usage examples

## perform a paginated query:
@posts = Post.paginate(:page => params[:page])

# or, use an explicit "per page" limit:
Post.paginate(:page => params[:page], :per_page => 30)

## render page links in the view:
<%= will_paginate @posts %>

And that's it! You're done. You just need to add some CSS styles to make those pagination links prettier.

You can customize the default "per_page" value:

# for the Post model
class Post
  self.per_page = 10

# set per_page globally
WillPaginate.per_page = 10

New in Active Record 3

# paginate in Active Record now returns a Relation
Post.where(:published => true).paginate(:page => params[:page]).order('id DESC')

# the new, shorter page() method[:page]).order('created_at DESC')

Customizing the 'page' parameter

By default, will_paginate knows what page you're on because of the :page parameter. You pass it in your controller to the pagination method like this: @articles.paginate :page => params[:page]

You can change the name for this if you have several things to paginate in a single HTML page.

will_paginate @articles, :param_name => :articles_page
will_paginate @pictures, :param_name => :pictures_page

Then in your controller:

@articles.paginate :page => params[:articles_page], ... other options
@pictures.paginate :page => params[:pictures_page], ... other options


Translations in can be found for various languages here :

Something went wrong with that request. Please try again.