WARNING

It's important to set the inverse_of as often as possible to your model's association attribute.

Has One

The HasOne association shows the unfolded view of your has_one association. It's like peaking on the Show view of that associated record. The user can also access the Attach and Detach buttons.

field :admin, as: :has_one

Options

-> attach_scope

Scope out the records the user sees on the Attach modal.

Default

nil

Possible values

field :user,
  as: :belongs_to,
  attach_scope: -> { query.non_admins }

Pass in a block where you attach scopes to the query object and parent object, which is the actual record where you want to assign the association. The block is executed in the ExecutionContext.

WARNING

The attach_scope will not filter the records in the listing from has_many or has_and_belongs_to_many associations. Use scope or a Pundit policy Scope for that.

field :members,
  as: :has_one,
  attach_scope: -> { query.where.not(team_id: parent.id) }

In this example, in the attach_scope, we ensure that when attaching members to a team, only those who are not already members will appear in the list of options.

-> loading

Controls how the association's content frame is loaded on the Show page.

By default an association loads its content as soon as its turbo-frame is revealed (the lazy behavior). The loading option lets you defer that fetch until the user explicitly asks for it, which is useful for heavy associations you don't want to load on every page view.

The default for every association is set globally via config.associations (loading: :lazy out of the box). Set loading: on a field to override that default per association.

Possible values

Value	Behavior
:manual	Renders a placeholder with a Load button. Nothing is fetched until the user clicks it. Once opened, the frame is remembered for 15 minutes by default (see auto_load_for).
{ mode: :manual }	Same as :manual.
{ mode: :manual, auto_load_for: 5.minutes }	Manual with a custom sliding memory window — once opened, the frame auto-loads (no placeholder, no button) on return visits for the given duration.
{ mode: :manual, auto_load_for: 0 }	Manual with no memory — the placeholder returns on every visit (0 or nil opts out).
:lazy / { mode: :lazy }	Native lazy loading (loads when the frame is revealed).

Manual loading

field :orders, as: :has_many, loading: :manual

The placeholder shows the association title, the (optional) description, and a Load button. On click, the real content is fetched into the frame. If the request fails (500, 404, network error), an inline error with a Retry button is rendered inside the frame instead of redirecting to the global failed-to-load page.

For a has_one association whose value is nil, the existing attach/create empty state is shown instead of a placeholder.

Remembering an opened frame

Once the user opens a manual frame, Avo remembers it for 15 minutes by default and skips the placeholder on return visits — the frame auto-loads directly. Pass auto_load_for to change that window:

field :orders, as: :has_many, loading: { mode: :manual, auto_load_for: 5.minutes }

The window is a sliding memory, not a delay: a short-lived cookie scoped per record + frame remembers the opened frame, and every return visit within the window refreshes it. Once the window lapses, the placeholder + Load button return.

Set auto_load_for: 0 (or nil) to opt out entirely — the placeholder then returns on every visit:

field :orders, as: :has_many, loading: { mode: :manual, auto_load_for: 0 }

The default window is configurable globally via config.associations.

Keep the description cheap with loading: :manual

The description lambda is evaluated to render the placeholder, before the user clicks Load — so a description that touches the database (e.g. -> { "#{query.count} orders" }) defeats the purpose of deferring the load. Branch on the loading_type attribute to skip the expensive work on the placeholder:

field :orders, as: :has_many, loading: :manual,
  description: -> { loading_type == :manual ? "Orders" : "#{query.count} orders" }

loading_type is :manual while the placeholder is shown and nil in every other render context.

Show on edit screens

By default, the has_one field is only visible in the show view. To make it available in the edit view as well, include the show_on: :edit option. This ensures that the has_one show view component is also rendered within the edit view.

Nested in Forms

You can use "Show on edit screens" to make the has_one field available in the edit view. However, this will render it using the show view component.

To enable nested creation for the has_one field, allowing it to be created and / or edited alongside its parent record within the same form, use the nested option which is a hash with configurable option.

The avo-nested gem

Nested association forms are provided by the avo-nested gem. Add it to your Gemfile using the same private gem source as your other Avo paid gems:

gem "avo-nested", source: "https://packager.dev/avo-hq/"

Run bundle install. If you have not set up packager.dev access yet, see Gem server authentication.

Keep in mind that this will display the field’s resource as it appears in the edit view.

-> nested

Enables this field as a nested form in the specified views.

Default value

{}

Possible values

A hash with the following options:

• on: Views in which to enable nesting. Accepted values:
  • :new - Enables nesting in the new view.
  • :edit - Enables nesting in the edit view.
  • :forms - Enables nesting in the new and edit views.
• limit: (Only for has_many and has_and_belongs_to_many fields) Hides the "Add" button when the specified limit is reached.

TIP

Setting nested: true is a shortcut for nested: { on: :forms }.

Example

# app/avo/resources/book.rb
class Avo::Resources::Book < Avo::BaseResource
  def fields
    # Shortcut for full nesting
    field :author, as: :has_one, nested: true

    # Explicit nesting on new only
    field :author, as: :has_one, nested: { on: :new }

    # Explicit nesting on edit only
    field :author, as: :has_one, nested: { on: :edit }

    # Explicit nesting on both new and edit
    field :author, as: :has_one, nested: { on: :forms }

    # Limit nested creation (for has_many or has_and_belongs_to_many only)
    field :authors,
      as: :has_one,
      nested: { on: [:new, :edit], limit: 2 }
  end
end