# Limit Extra

Allow the client to request a custom page limit with an optional selector UI. It is useful with APIs or user-customizable UIs.

Try it now!

Run the interactive demo from your terminal:

pagy demo
# or: bundle exec pagy demo

...and point your browser at http://0.0.0.0:8000

This extra works also with the Pagy::Keyset API and with the countless, searchkick, elasticsearch_rails and meilisearch extras

# Synopsis

# Default usage

pagy.rb (initializer)
require 'pagy/extras/limit' # works without further configuration

Controller
# enabled by default
@pagy, @records = pagy(collection)
# you can disable it explicitly for specific requests
@pagy, @records = pagy(collection, limit_extra: false)

# Custom usage

pagy.rb (initializer)
# optionally disable it by default
Pagy::DEFAULT[:limit_extra] = false # default true
# customize the defaults if you need to
Pagy::DEFAULT[:limit_param] = :custom_param # default :limit
Pagy::DEFAULT[:limit_max]   = 200 # default 100

Controller
# disabled by default by the above Pagy::DEFAULT[:limit_extras] = false
@pagy, @records = pagy(collection)
# explicitly enable it for specific requests
@pagy, @records = pagy(collection, limit_extra: true)

See Javascript (only if you use the pagy_limit_selector_js UI)

# Variables

Variable	Description	Default
`:limit_extra`	Enable or disable the feature	`true`
`:limit_param`	The name of the "limit" param used in the url	`:limit`
`:limit_max`	The max limit allowed. Set it to `nil` for no limit	`100`

You can use the :limit_extra variable to opt-out of the feature even when the extra is required.

This extra uses the :limit_param variable to determine the param it should get the :limit from.

The :limit_max is used to cap the :limit to that max. It is set to 100 by default. Set it to nil for no limit.

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.rb (initializer)
Pagy::DEFAULT[:limit_param] = :custom_param
Pagy::DEFAULT[:limit_max]   = 50

For a single instance (overriding the global default):

Controller
pagy(collection, limit_param: :custom_param, limit_max: 50)
Pagy.new(count: 100, limit_param: :custom_param, limit_max: 50)

Override 'limit' in Params

You can override the limit that the client sends with the params by passing the :limit explicitly. For example:

# this will ignore the params[:limit] (or any custom :my_limit)
# from the client for this instance, and override limit
pagy(scope, limit: 30)

# Methods

The limit extra adds the pagy_limit_selector_js helper to the Pagy::Frontend module.

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

Show items per page

It returns an empty string if the :limit_extra is false.

The method accepts also a few optional keyword arguments variables:

:id which adds the id HTML attribute to the nav tag
:item_name an already pluralized string that will be used in place of the default item/items

some_view.html.erb
<%== pagy_limit_selector_js(@pagy, item_name: 'Product'.pluralize(@pagy.count)) %>

Show Products per page

(see How to customize the item name)

When the limit is changed with the selector, pagy will reload the pagination UI using the selected limit. 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 change.

This method can take an extra id argument, which is used as the id attribute of the wrapper span tag.