Global Search
Users press β + K / Ctrl + K anywhere to search records across models. Results use each model's :search filter, respect Pundit policies and return up to 5 records per model. Models are searched in parallel; the modal also suggests matching model pages (typing "user" suggests the Users index page) and supports keyboard navigation.
Quick exampleβ
CmAdmin.configure do |config|
config.global_search_models = [User, Post, Order]
end
cm_index do
filter %i[email first_name last_name], :search
end
Setupβ
Step 1 β Register models for global searchβ
In your CmAdmin initializer (e.g., config/initializers/cm_admin.rb), add the models you want to be searchable:
CmAdmin.configure do |config|
config.global_search_models = [User, Post, Order]
end
Note: The order of models in this array determines the display order of results.
Step 2 β Ensure a search filter existsβ
Each model must have a :search filter defined in its cm_index block. Global search uses this filter to query records.
cm_admin do
cm_index do
filter %i[email first_name last_name], :search, placeholder: 'Search by name or email'
column :first_name
column :last_name
column :email
end
end
Important: If a model does not have a
:searchfilter on its index action, it will be silently skipped during global search.
Step 3 β Define cm_display_nameβ
By default, search results display as "ModelName #id" (e.g., "User #42"). To show a more meaningful title, define cm_display_name on your model:
class User < ApplicationRecord
def cm_display_name
"#{first_name} #{last_name}"
end
end
class Post < ApplicationRecord
def cm_display_name
title
end
end
Step 4 β Customize subtitle fieldsβ
Each search result can display additional metadata below the title. By default, global_search_fields is set to [:id, :created_at, :updated_at]. You can override this per model by setting the global_search_fields attribute:
cm_admin do
global_search_fields %i[email status created_at]
cm_index do
filter %i[email first_name], :search
column :email
column :status, field_type: :badge
column :created_at, field_type: :date
end
end
Note: The fields listed in
global_search_fieldsmust also be defined as columns incm_index. Only columns that exist in the index view and pass theirdisplay_ifcondition will be shown.
How It Worksβ
- User opens the search modal via β + K / Ctrl + K or by clicking the search icon.
- After typing at least 2 characters, a debounced request (300ms) is sent to the server.
- The server iterates over
global_search_modelsin parallel threads. - For each model:
- Checks if the user has
indexpolicy access. - Checks if a
:searchfilter is defined on the index action. - Applies policy scopes and default scopes.
- Runs the search filter and limits results to 5 records.
- Checks if the user has
- Results are sorted by the original model order and rendered via Turbo Stream.
- Additionally, model pages matching the query string are suggested at the bottom.
Optionsβ
CmAdmin.config.global_search_modelsβ
| Property | Type | Default | Description |
|---|---|---|---|
global_search_models | Array | [] | Array of ActiveRecord model classes to include in global search results. |
global_search_fields (per model)β
| Property | Type | Default | Description |
|---|---|---|---|
global_search_fields | Array | [:id, :created_at, :updated_at] | Array of field identifiers to display as subtitle in search results. |
Environment Variablesβ
| Variable | Default | Description |
|---|---|---|
GLOBAL_SEARCH_THREAD_POOL_SIZE | 5 | Number of threads used for concurrent model searches. |
Recipesβ
# config/initializers/cm_admin.rb
CmAdmin.configure do |config|
config.global_search_models = [User, Post, Comment]
end
# app/models/user.rb
class User < ApplicationRecord
def cm_display_name
"#{first_name} #{last_name}"
end
cm_admin do
icon_name 'fa fa-user'
global_search_fields %i[email created_at]
cm_index do
filter %i[email first_name last_name], :search, placeholder: 'Search users'
column :first_name
column :last_name
column :email
column :created_at, field_type: :date
end
end
end
# app/models/post.rb
class Post < ApplicationRecord
def cm_display_name
title
end
cm_admin do
icon_name 'fa fa-file-text'
global_search_fields %i[status created_at]
cm_index do
filter %i[title], :search, placeholder: 'Search posts'
column :title
column :status, field_type: :badge
column :created_at, field_type: :date
end
end
end
Notesβ
- Models without a
:searchfilter or without index policy access are automatically excluded. - The search respects all default scopes and action-level scopes configured on the model.
- The search modal will not open if another modal is already visible on the page.
- The placeholder in the search input automatically shows the first 3 configured model names.