Search API

Per-option reference for search. For task-oriented documentation and worked examples, see the Search guide.

Resource-level options live in the self.search hash on the resource class; global search options live in config/initializers/avo.rb:

class Avo::Resources::User < Avo::BaseResource
  self.search = {
    query: -> { query.ransack(name_cont: q, m: "or").result(distinct: false) },
    item: -> { {title: record.name} },
    hide_on_global: false,
    display_count: true
  }
end

Avo.configure do |config|
  config.global_search = {enabled: true, navigation_section: true, search_on_type: true}
  config.search_results_count = 8
end

Resource configuration

-> query

The search query, executed with Avo::ExecutionContext whenever any search surface runs against this resource. Without it, the resource has no Index search bar and is skipped by the global search.

self.search = {
  query: -> { query.ransack(name_cont: q, m: "or").result(distinct: false) }
}

• Type: Proc
• Default: nil — search disabled for the resource
• Locals: q (stripped search string), query (base scope with authorization scopes applied), params, search_type, plus all Avo::ExecutionContext attributes
• Return: an ActiveRecord::Relation, or an Array of hashes for custom search providers

-> item

Configures how each result row renders in the global search palette, the direct-match section, and searchable association pickers. The resource-index search bar is unaffected — it re-renders the regular index views. The proc has access to record and resource and returns a hash with the following keys:

Option	Description	Default	Possible Values
title	The title of the result	Resource title	Any string
description	The description of the result	nil	Any string
image_url	The URL of the image to display in the result	nil	Any valid URL
image_format	The format of the image to display in the result	:circle	:square, :rounded, :circle
path	The path to navigate to when clicking the result	Record show page	Any valid path

self.search = {
  query: -> { query.ransack(name_cont: q, m: "or").result(distinct: false) },
  item: -> do
    {
      title: "[#{record.id}] #{record.name}",
      description: record.truncated_body,
      image_url: main_app.url_for(record.cover_photo),
      image_format: :rounded,
      path: avo.resources_post_path(record, custom: "search")
    }
  end
}

• Type: Proc returning a Hash
• Default: nil — rows render the record's title with no description or image

-> hide_on_global

Excludes the resource from the global search — the palette results, the direct-match lookup, and the dedicated results page. The search bar on the resource's own Index view keeps working.

self.search = {
  query: -> { query.ransack(id_eq: q, m: "or").result(distinct: false) },
  hide_on_global: true
}

• Type: Boolean
• Default: false

-> display_count

Whether the global search shows result counts in each resource's header — "Users (8 of 21)". Counting runs an extra query per resource; disable it on large datasets or when a custom search provider can't count.

self.search = {
  query: -> { query.ransack(name_cont: q, m: "or").result(distinct: false) },
  display_count: false
}

A lambda works too, evaluated with access to all attributes of Avo::ExecutionContext:

self.search = {
  display_count: -> { current_user.admin? }
}

• Type: Boolean or Proc
• Default: true

search_type

A local injected into the query proc identifying which surface triggered the search, so one proc can serve different queries per surface.

Value	Surface
:resource	resource-index search bar
:global	navbar ⌘K palette and its dedicated results page
:association	searchable association picker on edit forms and the attach modal

INFO

search_type is injected by Avo. On a Community-only install the local is not defined and referencing it in the proc raises an error. The kanban board card picker also does not inject search_type (or a q local) — read the term from params[:q] and detect the board with params[:for_kanban_board].

Global search configuration

License: Add-on

Keys of the config.global_search hash in config/initializers/avo.rb. Also listed in the customization API.

-> enabled

Whether the global search renders at all — the navbar trigger, the Cmd + K shortcut, and the dedicated results page.

config.global_search = {
  enabled: -> { current_user.is_admin? }
}

• Type: Boolean or Proc (evaluated with Avo::ExecutionContext)
• Default: true

-> navigation_section

Whether the palette shows the "Go to" section — links to the Index page of every resource the current user can access, filtered as the user types.

config.global_search = {
  navigation_section: false
}

• Type: Boolean or Proc (evaluated with Avo::ExecutionContext)
• Default: true

-> search_on_type

Whether typing in the palette triggers the search automatically. When false, the dropdown still opens on focus or Cmd + K, but the user must press Enter to run the search and navigate to the dedicated results page.

config.global_search = {
  search_on_type: false
}

• Type: Boolean
• Default: true

WARNING

Unlike enabled and navigation_section, this key does not accept a lambda — any Proc is truthy, so it would behave as true.

Limiting results

-> search_results_count

How many results Avo shows per resource on search surfaces. Applied only to queries that return an ActiveRecord::Relation without a .limit() of their own — a .limit() in the query proc always wins. Arrays from custom search providers are never auto-capped. The dedicated global search results page ignores the limit and lists every match.

config.search_results_count = 16

• Type: Integer
• Default: 8

The delay before a keystroke fires the search request is controlled by config.search_debounce.

Custom search providers

When the query proc returns an Array instead of a relation, each element must be a hash with this structure:

{
  _id: 1,
  _label: "The label",
  _url: "https://example.com/records/1",
  _description: "Some description about the record",
  _avatar: "https://example.com/avatar.jpg",
  _avatar_type: :rounded
}

Key	Description
_id	The record's identifier
_label	Row title; the search term is highlighted inside it
_url	Where clicking the row navigates
_description	Optional row description
_avatar	Optional image URL
_avatar_type	:square, :rounded, or :circle

WARNING

With array results the result count is not available, and search_results_count is not applied — cap the array in the proc with .first(N) if needed.