Searchable associations API

Per-option reference for searchable. For task-oriented documentation, see the Searchable associations guide.

Form	Value	Behavior
Boolean	true	Searchable picker using the target resource's self.search
Boolean	false	Standard <select>
Hash	{ query:, item:, enabled: }	Per-field overrides

Boolean form

Pass searchable: true on the association field. The picker reads query: and item: from the target resource's self.search hash. Nothing is configured on the field itself.

If the target resource has no self.search[:query], the picker stays empty. If it has no self.search[:item], rows fall back to the resource title.

# app/avo/resources/course.rb
class Avo::Resources::Course < Avo::BaseResource
  def fields
    field :links, as: :has_many, searchable: true
  end
end

# app/avo/resources/link.rb
class Avo::Resources::Link < Avo::BaseResource
  self.search = {
    query: -> {
      query.ransack(title_cont: q).result(distinct: false)
    },
    item: -> {
      {title: record.title, description: record.url}
    }
  }
end

The links field on Avo::Resources::Course uses both procs from Avo::Resources::Link.

Hash form

Pass a hash when a single picker needs different query:, item:, or enabled: behavior than the target resource provides.

# app/avo/resources/review.rb
class Avo::Resources::Review < Avo::BaseResource
  def fields
    field :user,
      as: :belongs_to,
      searchable: {
        query: -> {
          query.ransack(name_cont: q).result(distinct: false)
        },
        item: -> {
          {title: "Reviewer: #{record.first_name}", description: record.email}
        },
        enabled: -> { current_user.admin? }
      }
  end
end

Options

-> query

Proc that filters records as the user types.

• Type: Proc / Lambda
• Where: searchable: { query: } on the field, or self.search[:query] on the target resource
• Default: nil — falls back to self.search[:query]. If neither is set, the picker stays empty.
• Precedence: field-level overrides resource-level
• Cap: same rules as Limiting results
• Locals: q, query, params, search_type, parent_record, parent_resource

parent_record can be nil on create forms. Guard with &. when referencing it.

# app/avo/resources/review.rb
class Avo::Resources::Review < Avo::BaseResource
  def fields
    field :user, as: :belongs_to, searchable: {
      query: -> { query.ransack(name_cont: q).result(distinct: false) }
    }
  end
end

Polymorphic fields

One proc runs for every declared type. Branch on query.klass when the search needs to differ per type.

# app/avo/resources/comment.rb
class Avo::Resources::Comment < Avo::BaseResource
  def fields
    field :commentable,
      as: :belongs_to,
      polymorphic_as: :commentable,
      types: [::Post, ::Project],
      searchable: {
        query: -> {
          case query.klass.name
          when "Post"    then query.ransack(body_cont: q).result(distinct: false)
          when "Project" then query.ransack(name_cont: q).result(distinct: false)
          end
        }
      }
  end
end

-> item

Proc that renders each row in the picker dropdown.

• Type: Proc / Lambda
• Where: searchable: { item: } on the field, or self.search[:item] on the target resource
• Default: nil — falls back to self.search[:item], then the resource title
• Precedence: field-level overrides resource-level
• Locals: record, resource

Return value 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

# app/avo/resources/review.rb
class Avo::Resources::Review < Avo::BaseResource
  def fields
    field :user, as: :belongs_to, searchable: {
      item: -> do
        {
          title: "Reviewer: #{record.first_name}", 
          description: record.email
        }
      end
    }
  end
end

-> enabled

Toggles whether the picker renders as a searchable widget.

• Type: Boolean, or Proc / Lambda returning a Boolean
• Where: searchable: { enabled: } on the field
• Default: true (when omitted)
• Falsy: field renders the standard <select> instead
• Locals: record, resource, current_user

# app/avo/resources/review.rb
class Avo::Resources::Review < Avo::BaseResource
  def fields
    field :user, as: :belongs_to, searchable: {
      enabled: -> { current_user.admin? }
    }
  end
end