Checkbox List

The CheckboxList field renders a list of checkboxes for selecting multiple values from a finite set of options. Use it when users should see the choices directly instead of opening a select.

# app/avo/resources/team.rb
field :team_member_ids,
  as: :checkbox_list,
  options: -> {
    User.active.order(:name).map do |user|
      {
        id: user.id,
        title: user.name,
        avatar_url: user.avatar_url,
        image_format: :circle,
        description: user.email
      }
    end
  },
  inline_search: true

You must supply options; there is no default list. Without inline_search, the field displays the choices without a search input. Images are circular unless you choose another shape.

Define a fixed set of choices

For choices that do not depend on the record or request, pass an array of hashes. Give each choice an id to submit and a title to display. Add a description when users need help distinguishing similar choices.

# app/avo/resources/user.rb
field :role_ids,
  as: :checkbox_list,
  options: [
    {id: 1, title: "Admin", description: "Can manage the account"},
    {id: 2, title: "Editor", description: "Can update content"},
    {id: 3, title: "Viewer", description: "Can read content"}
  ]

Load choices from records

Use a lambda when the choices come from a query. Computed options run inside Avo::ExecutionContext, with access to record, resource, view, field, params, request, view_context, and the other execution context helpers.

# app/avo/resources/team.rb
field :user_ids,
  as: :checkbox_list,
  options: -> {
    users = User.order(:name)

    users.map do |user|
      {
        id: user.id,
        title: user.name,
        avatar_url: user.avatar_url,
        description: user.email
      }
    end
  }

Add images to choices

Provide avatar_url or image_url to show an image before the title. Set image_format to :rounded or :square for non-circular images. Use image_alt or avatar_alt to customize the alt text; otherwise the title is used.

Help users find a choice

Enable inline search to filter the options already rendered on the page by title and description. Search is case-insensitive and does not make server requests, so use it for small and medium option sets. Checked choices stay selected and are still submitted when hidden by search.

# app/avo/resources/team.rb
field :team_member_ids,
  as: :checkbox_list,
  options: -> { User.active.order(:name).map { |user| {id: user.id, title: user.name} } },
  inline_search: true

You can also use a lambda to decide whether to show the search input in the field's execution context. It must return true to enable search.

Explain a limited set of results

If your query intentionally limits the available choices, add a hint entry to explain that limit. Its title appears below the list, without a checkbox. The hint does not load more records.

# app/avo/resources/team.rb
field :user_ids,
  as: :checkbox_list,
  options: -> {
    User.order(:name).limit(50).map { |user| {id: user.id, title: user.name} } +
      [{title: "Showing up to 50 users", hint: true}]
  }

Save multiple selections

The field submits an array of selected option ids as strings. This works well with Rails collection writers like team_member_ids=. Integer and string ids match the same stored selection, and blank submitted values are removed before assignment. Clearing all checkboxes assigns an empty array.

For configuration shared with other fields, see Shared field options.