#

## :icon-search:  :rails_active_search

---

`:rails_active_search` is a [SEARCH](/guides/choose-right/#search) paginator for `ActiveSearch` (`rails-active_search` gem) search results.

[!button corners="pill" variant="info" icon="play-24" text="Check it out with `bundle exec pagy active_search`"](/sandbox/playground/#active-search)

=== :icon-tools:  Usage

+++ Active mode

!!!success Pagy searches and paginates
You use the `pagy_search` method in place of the `search` method.
!!!

```ruby Model
extend Pagy::Search
```

```ruby Controller
# Get the collection (ActiveSearch keyword arguments, e.g., index: or scope:, are passed through)
search = Article.pagy_search(params[:q])
# Chain any ActiveSearch::Query method that returns a query (e.g., filter, sort, highlight)
search = Article.pagy_search(params[:q]).filter(status: 'published').sort(published_at: :desc)
# Paginate it: @results is the ActiveSearch::Results of the page
@pagy, @results = pagy(:rails_active_search, search, **options)
```

!!!warning
Do not chain the pagination methods (`limit`, `offset`, `page`) nor the methods that end the chain (e.g., `results`, `to_native_query`).
!!!

+++ Passive mode

!!!success You search and paginate
Pagy creates its object out of your result.
!!!

```ruby Controller
# Standard results (already paginated)
@results = Article.search(params[:q]).limit(10).offset(20).results
# or
@results = Article.search(params[:q]).page(3, per_page: 10).results
# Get the pagy object out of it
@pagy    = pagy(:rails_active_search, @results, **options)
```

!!!warning
The `:limit` and `:page` are extracted from the results, so use a single Integer `per_page` with `page`: an Array of page sizes is not supported.
!!!

+++

!!!
Search paginators use the same positional technique as [:offset](offset.md) paginators, with shared options and readers.
!!!

==- :icon-sliders:  Options

`search_method: :my_search`
: Customize the name of the `ActiveSearch` search method to use in active mode (default `:search`).

`limit: 10`
: Specifies the number of items per page (default: `20`).

`client_limit: 200`
: Allow the client to request a `:limit` up to `:client_limit`. A higher requested `:limit` is silently capped.

  **IMPORTANT** If falsey or zero, the client cannot request any `:limit`.

`page: force_page`
: Set it only to force the current `:page`. _(It is set automatically from the request param)_

`request: request || hash`
: Pagy tries to find the `Rack::Request` at `self.request`. Set it only when it's not directly available in your code (e.g., Hanami, standalone app, test,...). For example:
    ```ruby
    hash_request = { base_url: 'http://www.example.com',
                     path:     '/path',
                     params:   { 'param1' => 1234 }, # The string-keyed params hash from the request
                     cookie:   'xyz' }               # The 'pagy' cookie, only for keynav
    ```

`jsonapi: true`
: Enables JSON:API-compliant URLs with nested query string (e.g., `?page[number]=2&page[size]=100`).

`root_key: 'my_root'`
: Set it to enable nested URLs with nested query string `?my_root[page]=2&my_root[limit]=100`. Use it to handle multiple pagination objects in the same request.

`page_key: 'my_page'`
: Set it to change the key string used for the `:page` in URLs (default `'page'`).

`limit_key: 'my_limit'`
: Set it to change the key string used for the `:limit` in URLs (default `'limit'`).

==- :icon-mention:  Readers

`offset`
: The OFFSET used in the SQL query.

`count`
: The collection count.

`from`
: The position in the collection of the first item on the page. _(Different Pagy classes may use different value types for it)._

`to`
: The position in the collection of the last item on the page. _(Different Pagy classes may use different value types for it)._

`last`
: The last page.

`pages`
: The number of pages.

`previous`
: The previous page.

`next`
: The next page.

`page`
: The current page.

`limit`
: The items per page.

`in`
: The actual items in the page.

`records`
: The fetched records for the current page.

`options`
: The hash of options of the object.

===