© 2017-2020 Domizio DemichelisMIT License

➡ Chat Support on Gitter ➡

Items Extra

Allow the client to request a custom number of items per page with an optional selector UI. It is useful with APIs or higly user-customizable apps.

It works also with the countless, searchkick and elasticsearch_rails extras.


See extras for general usage info.

In the pagy.rb initializer:

require 'pagy/extras/items'

Pagy::VARS[:items_param] = :custom_param       # default :items
Pagy::VARS[:max_items]   = 100                 # default

See Javascript (only if you use the pagy_items_selector_js UI)



Variable Description Default
:items_param the name of the items param used in the url. :items
:max_items the max items allowed to be requested. Set it to nil for no limit. 100

This extra uses the :items_param variable to determine the param it should get the number of :items from.

The :max_items is used to cap the number of items to that max. It is set to 100 by default. If you don’t want to limit the max requested number of items per page, you can set it to nil.

You may want to customize the variables. Depending on the scope of the customization, you have a couple of options:

As a global default:

Pagy::VARS[:items_param] = :custom_param
Pagy::VARS[:max_items]   = 50

For a single instance (overriding the global default):

pagy(scope, items_param: :custom_param, max_items: 50)
Pagy.new(count:100, items_param: :custom_param, max_items: 50)

Notice: you can override the items that the client sends with the params by passing the :items explicitly. For example:

# this will ignore the params[:items] (or any custom :param_name)
# from the client for this instance, and serve 30 items
pagy(scope, items: 30)


The items extra overrides a couple of builtin methods and adds a helper to the Pagy::Frontend module. All the overridden methods are alias-chained with *_with_items and *_without_items)

pagy_get_vars(collection, vars)

This extra overrides the pagy_get_vars method of the Pagy::Backend module in order to set the :items variable, pulled from the request-params.

pagy_countless_get_vars(collection, vars)

This extra overrides the pagy_countless_get_vars method of the Pagy::Backend module (added by the countless extra) in order to set the :items variable, pulled from the request-params.

pagy_url_for(page, pagy)

This extra overrides also the pagy_url_for method of the Pagy::Frontend module in order to add the :items_param param to the url of the links.

pagy_items_selector_js(pagy, …)

This helper provides an items selector UI, which allows the user to select any arbitrary number of items per page (below the :max_items number) in a numeric input field. It looks like:

Show items per page

or, if you use the :i18n_key variable you can get a custom/collection-specific output:

Show Products per page

(see Customizing the item name)

When the items number is changed with the selector, pagy will reload the pagination UI using the selected items per page. It will also request the right page number calculated in order to contain the first item of the previously displayed page. That way the new displayed page will roughly show the same items in the collection before the items change.

This method can take an extra id argument, which is used to build the id attribute of the nav tag. Since the internal automatic id generation is based on the code line where you use the helper, you must pass an explicit id if you are going to use more than one *_js call in the same line for the same file.

Notice: passing an explicit id is also a bit faster than having pagy to generate one.