Ransack Documentation

Ransack is designed for Ruby on Rails applications and supports the following environments:

• Rails: 7.2, 8.0
• Ruby: 3.1 and later

When using internationalization gems like Globalize, sorting on translated attributes requires specific handling to ensure joins are correctly established.

Using View Helpers

You can use sort_link directly with the translation attribute:

<%= sort_link @q, :translations_name %>
<%= sort_link @q, :category_translations_name %>

Programmatic Sorting

When setting sorts in the controller, you must ensure the necessary joins are included in the ActiveRecord relation to prevent errors.

Basic approach:

@q = Book.ransack(s: 'category_translations_name asc')
@books = @q.result.joins(:translations)

Complex scenarios (multiple translations/nested associations): Use .includes to ensure all join dependencies are loaded:

@q = Book.ransack(s: 'category_translations_name asc')
@books = @q.result.includes(:translations, category: :translations)

Ransack allows you to create custom search functions called ransackers using Arel. A ransacker method is defined in your model and must return an Arel node that supports standard predicate methods (like eq, cont, matches, etc.).

Note: Ransackers are an expert feature. For better performance and scalability, prefer searching on dedicated database search fields whenever possible rather than converting/ransacking data on the fly.

# in the model:
ransacker :reversed_name, formatter: proc { |v| v.reverse } do |parent|
  parent.table[:name]
end

To ensure a consistent sort order when no user-provided sorting is present, you can manually assign values to the @q.sorts attribute in your controller's index action. This should be done if @q.sorts is empty.

For a single sort field:

@q.sorts = 'title asc'

For multiple sort fields:

@q.sorts = ['title asc', 'created_at desc']

# app/controllers/posts_controller.rb
class PostsController < ActionController::Base
  def index
    @q = Post.ransack(params[:q])
    @q.sorts = 'title asc' if @q.sorts.empty?

    @posts = @q.result(distinct: true)
  end
end

If you want to use the cont (contains) predicate on an integer field (like id), you must first convert the integer to a string using a ransacker.

PostgreSQL

# in the model:
ransacker :id do
  Arel.sql("to_char(id, '9999999')")
end

MySQL

# in the model:
ransacker :id do
  Arel.sql("CONVERT(#{table_name}.id, CHAR(8))")
end

Usage in View

<%= f.search_field :id_cont, placeholder: 'Id' %>
<%= sort_link(@search, :id) %>

# PostgreSQL version
ransacker :id do
  Arel.sql("to_char(id, '9999999')")
end

# View usage
<%= f.search_field :id_cont, placeholder: 'Id' %>
<%= sort_link(@search, :id) %>

To deploy the documentation using SSH, use the yarn deploy command with the USE_SSH environment variable set to true.

USE_SSH=true yarn deploy

You can customize the labels used for predicates and attributes in Ransack forms by adding entries to your application's translation files (e.g., locales/en.yml).

To customize predicates, use the ransack.predicates key. To customize attribute labels specifically for Ransack, use the ransack.attributes.[model_name].[attribute_name] key.

en:
  ransack:
    asc: ascending
    desc: descending
    predicates:
      cont: contains
      not_cont: not contains
      start: starts with
      end: ends with
      gt: greater than
      lt: less than
    attributes:
      person:
        name: Full Name
      article:
        title: Article Title
        body: Main Content

To export data to CSV while preserving the current Ransack search parameters, you can generate a link that merges the existing search parameters (params[:q]) with the desired :csv format.

In your view, check if params[:q] exists. If it does, pass the specific search attributes from params[:q] into the URL helper along with format: :csv. If no search is active, simply link to the index path with format: 'csv' to export the full collection.

<% if params[:q] %>
  <%= link_to 'Export 1', dashboard_index_path({name: params[:q][:name_cont]}.merge({format: :csv})) %>
<% else %>
  <%= link_to 'Export 2', dashboard_index_path(format: 'csv') %>
<% end %>

To add Ransack to your Rails application, add the following line to your Gemfile and run bundle install.

gem 'ransack'

Use the sort_link helper within your view templates to generate links that allow users to toggle sorting for specific columns. The helper takes the Ransack search object (@q), the attribute name to sort by, and an optional label string.

Example usage in an ERB template:

<th><%= sort_link(@q, :title, "Title") %></th>
<th><%= sort_link(@q, :category, "Category") %></th>