Field options API

Per-option reference for the options every Avo field accepts. For task-oriented documentation and worked examples, see the Field options guide.

All options are passed to the field method inside a resource's def fields:

ruby

class Avo::Resources::User < Avo::BaseResource
  def fields
    field :name, as: :text, sortable: true, help: "The user's full name"
  end
end

Options that only certain field types respond to (like options on the select field) are documented on each field's page.

Naming and description

`-> name`

The label displayed for the field. When omitted, Avo humanizes the field's id (is_available becomes "Is available"), first checking for an i18n translation under avo.field_translations.<id>.

ruby

field :is_available, as: :boolean, name: "Availability"

Type: String or Proc
Default: the humanized field id
i18n key: avo.field_translations.<field_id> — used when defined, otherwise the id is humanized

`-> translation_key`

The i18n key used to translate the field's label, help, and placeholder. See the i18n page for the full lookup rules.

ruby

field :is_available, as: :boolean, translation_key: "avo.field_translations.availability"

Type: String
Default: avo.field_translations.<field_id>

`-> help`

Extra text displayed below the input on the form views (New and Edit). Accepts HTML. Use label_help to show text on every view instead.

ruby

field :password, as: :password, help: 'Verify the password strength <a href="http://www.passwordmeter.com/">here</a>.'

Type: String (HTML allowed) or Proc
Default: nil
i18n key: avo.field_translations.<field_id>.help — used when defined

`-> label_help`

Help text displayed below the field's label on every view. Accepts HTML.

ruby

field :custom_css, as: :code, label_help: "This enables you to edit the user's custom styles."

Type: String (HTML allowed) or Proc
Default: nil

`-> placeholder`

The placeholder shown inside empty inputs on the New and Edit views. Only applies to fields that render a text-like input.

ruby

field :name, as: :text, placeholder: "John Doe"

Type: String or Proc
Default: the field's name
i18n key: avo.field_translations.<field_id>.placeholder — used when defined

Visibility on views

Four methods control which views a field appears on. They all accept a single value or an array of values from this table:

Value	Meaning
`:index`	the `Index` view
`:show`	the `Show` view
`:new`	the `New` view
`:edit`	the `Edit` view
`:preview`	the preview popover
`:forms`	`:new` and `:edit`
`:display`	`:index` and `:show`
`:all`	every view — only for `show_on` and `hide_on`

By default a field is visible on :index, :show, :new, and :edit, and hidden on :preview.

INFO

A few fields override these defaults — for example, the id field hides itself on the form views.

`-> show_on`

Shows the field on the given views, on top of the defaults.

ruby

field :body, as: :textarea, show_on: :preview

Type: Symbol or Array of Symbols
Values: see the table above, including :all

`-> hide_on`

Hides the field on the given views, keeping the defaults elsewhere.

ruby

field :body, as: :textarea, hide_on: [:index, :show]

Type: Symbol or Array of Symbols
Values: see the table above, including :all

`-> only_on`

Shows the field exclusively on the given views and hides it everywhere else.

ruby

field :body, as: :textarea, only_on: :forms

Type: Symbol or Array of Symbols
Values: see the table above, except :all

`-> except_on`

Shows the field everywhere except the given views.

ruby

field :body, as: :textarea, except_on: :forms

Type: Symbol or Array of Symbols
Values: see the table above, except :all

`-> visible`

Conditionally shows or hides the field. The block is executed in Avo::ExecutionContext and has access to the context object and the current resource (the record is available as resource.record).

ruby

field :is_featured, as: :boolean, visible: -> { context[:user].is_admin? }

Type: Boolean or Proc
Default: true

WARNING

On form submissions, the visible block is evaluated in the create and update controller actions, where resource.record can be nil (on creation). Use safe navigation: resource.record&.enabled?.

Formatting values

Formatter blocks are executed in Avo::ExecutionContext and have access to value, record, resource, view, and field, plus the usual defaults (context, params, view_context, current_user).

`-> format_using`

Formats the field's value on every view — including the value rendered inside inputs on the form views.

ruby

field :price, as: :number, format_using: -> { view_context.number_to_currency(value) }

Type: Proc
Default: nil

Copyable values

When combined with copyable, the formatted value is what gets copied to the clipboard, not the original database value.

`-> format_{view}_using`

View-scoped variants of format_using. Each one formats the value only on the view (or view group) it names.

Option	Applies on
`format_index_using`	`Index`
`format_show_using`	`Show`
`format_edit_using`	`Edit`
`format_new_using`	`New`
`format_form_using`	`New` and `Edit`
`format_display_using`	`Index` and `Show`

ruby

field :is_writer, format_display_using: -> { value.present? ? "👍" : "👎" }

Type: Proc
Default: nil

When several formatters are declared, the most specific one wins and the others are ignored — they do not chain:

View	Order of precedence
`Index`	`format_index_using` → `format_display_using` → `format_using`
`Show`	`format_show_using` → `format_display_using` → `format_using`
`Edit`	`format_edit_using` → `format_form_using` → `format_using`
`New`	`format_new_using` → `format_form_using` → `format_using`

`-> update_using`

Parses the raw form value before it is stored in the database on create and update. The block's return value is what gets saved. Also receives key (the attribute being written) alongside the usual variables.

ruby

field :metadata,
  as: :code,
  update_using: -> do
    ActiveSupport::JSON.decode(value)
  end

Type: Proc
Default: nil

Form behavior

`-> required`

Adds an asterisk to the field's label, marking it as mandatory. Purely cosmetic — add the actual validation to your model (validates :name, presence: true). The block is executed in Avo::ExecutionContext with access to view, record, resource, params, context, view_context, and current_user.

ruby

field :name, as: :text, required: -> { view == :new }

Type: Boolean or Proc
Default: nil — the asterisk is added automatically when the model has a presence validator on the attribute

`-> disabled`

Renders the input as disabled on the New and Edit views and ignores the field's value on save. A bad actor re-enabling the input in the DOM cannot write to the record. The block runs in Avo::ExecutionContext with the same variables as required.

ruby

field :name, as: :text, disabled: -> { view == :edit }

Type: Boolean or Proc
Default: false

`-> readonly`

Renders the input as disabled on the New and Edit views, but — unlike disabled — the value is still processed on save. The block runs in Avo::ExecutionContext with the same variables as required.

ruby

field :name, as: :text, readonly: true

Type: Boolean or Proc
Default: false

WARNING

readonly is a UI affordance only. A user can re-enable the input in the DOM and submit an arbitrary value. Use disabled to protect the attribute server-side.

`-> default`

Pre-fills the field on the New view (and in action modals) when the record's attribute is nil. The block is executed in Avo::ExecutionContext with access to record, resource, view, and parent.

ruby

field :level, as: :select, options: {Beginner: :beginner, Advanced: :advanced}, default: -> { Time.now.hour < 12 ? "advanced" : "beginner" }

Type: any value or Proc
Default: nil

`-> nullable`

Stores NULL in the database instead of an empty value. On form submission, any submitted value included in null_values is cast to nil before the record is saved.

ruby

field :body, as: :textarea, nullable: true

Type: Boolean
Default: false

`-> null_values`

The set of submitted values that nullable converts to nil.

ruby

field :body, as: :textarea, nullable: true, null_values: ["0", "", "null", "nil", nil]

Type: Array
Default: [nil, ""]

`-> autocomplete`

Forwarded verbatim to the input's autocomplete HTML attribute on fields that render a text-like input (text, number, password, and similar).

ruby

field :one_time_password, as: :text, autocomplete: "one-time-code"

Type: String
Default: nil
Values: any valid HTML autocomplete token

Index view

`-> sortable`

Makes the column sortable on the Index view. For computed fields or associations — where Avo can't infer the column to sort by — pass a block that receives query and direction and returns a query.

ruby

field :name, as: :text, sortable: true

field :last_commented_at,
  as: :date,
  sortable: -> {
    query.includes(:comments).order("comments.created_at #{direction}")
  }

Type: Boolean or Proc
Default: false (the id field defaults to true)

`-> summarizable`

Adds a chart icon to the column's table header. Clicking it opens a popover with a chart of the column's data distribution.

ruby

field :status, as: :select, summarizable: true

Type: Boolean
Default: false

`-> link_to_record`

Renders the field's Index table cell as a link to the record.

ruby

field :name, as: :text, link_to_record: true

Type: Boolean
Default: false
Available on: id, text, gravatar, and belongs_to fields

Related: the global id_links_to_resource configuration links every id field automatically.

Layout and rendering

`-> width`

The percentage of horizontal space the field takes inside its panel. Adjacent fields with widths below 100 sit on the same row.

ruby

field :first_name, width: 50
field :last_name,  width: 50

Type: Integer or Proc
Default: 100
Values:

`width`	Approx. fraction
`25`	¼
`33`	⅓
`50`	½
`66`	⅔
`75`	¾
`100`	full row (default)

Unlisted values fall back to the full row width.

INFO

Any width below 100 automatically marks the field as stacked.

`-> stacked`

Renders the field's label above its value instead of beside it.

ruby

field :meta, as: :key_value, stacked: true

Type: Boolean
Default: nil — falls back to the config.field_wrapper_layout initializer option (:inline unless changed to :stacked)

`-> html`

Attaches style, classes, and data HTML attributes to the field's wrapper, label, or input, per view. See the HTML attributes page for the full structure.

ruby

field :users_required, as: :number, html: {index: {wrapper: {classes: "text-right"}}}

Type: Hash or Proc
Default: nil

`-> components`

Overrides the view components used to render the field, per view. Keys follow the <view>_component pattern (index_component, show_component, edit_component); values are component classes or class names as strings. The block is executed in Avo::ExecutionContext with access to resource, record, view, params, and more.

ruby

field :description,
  as: :text,
  components: {
    index_component: Avo::Fields::Admin::TextField::IndexComponent,
    show_component: Avo::Fields::Admin::TextField::ShowComponent,
    edit_component: "Avo::Fields::Admin::TextField::EditComponent"
  }

Type: Hash, or Proc returning a Hash
Default: {}

Initializer

Keep the same initializer signature on your custom components as the original field view component.

`-> copyable`

Shows a clipboard icon when hovering over the field's value on the Show and Index views, letting users copy it. Applies to fields that render text values.

ruby

field :name, as: :text, copyable: true

Type: Boolean
Default: false

INFO

The copied value is the displayed value — if the field uses format_using, the formatted result is what lands in the clipboard.

Advanced

`-> for_attribute`

Reads from and writes to a different model attribute than the field's id. Useful for declaring two fields backed by the same attribute.

ruby

field :secondary_field_for_status,
  as: :badge,
  for_attribute: :status,
  options: {info: :one, success: :two, warning: :three}

Type: Symbol or String
Default: nil — the field's id is used as the attribute

`-> meta`

Sends arbitrary data to the field, readable inside components and templates as @field.meta. Useful with custom fields or custom components.

ruby

field :status, as: :custom_status, meta: {foo: :bar}

Type: Hash or Proc
Default: nil

`-> react_on`

Re-evaluates the field when other fields change in the form, refreshing @record with the latest form values. Requires the avo-reactive_fields add-on gem (see the Avo 4 upgrade guide for the packager.dev source).

ruby

field :city,
  as: :select,
  react_on: :country,
  options: -> { Course.cities.dig(@record.country&.to_sym) || [""] }

Type: Symbol, Array of Symbols, or :all
Default: nil
Values: a single field (:field_one), multiple fields ([:field_one, :field_two]), or :all (react to every field in the form)

Updates run when a watched field's value is committed — the change event. For selects, checkboxes, and radios that's on selection; for text inputs and textareas it's when the input loses focus. To read a field's original value inside a block, use the *_was methods.

Field options API ​

Naming and description ​

-> name

-> translation_key

-> help

-> label_help

-> placeholder

Visibility on views ​

-> show_on

-> hide_on

-> only_on

-> except_on

-> visible

Formatting values ​

-> format_using

-> format_{view}_using

-> update_using

Form behavior ​

-> required

-> disabled

-> readonly

-> default

-> nullable

-> null_values

-> autocomplete

Index view ​

-> sortable

-> summarizable

-> link_to_record

Layout and rendering ​

-> width

-> stacked

-> html

-> components

-> copyable

Advanced ​

-> for_attribute

-> meta

-> react_on

Field options API

Naming and description

`-> name`

`-> translation_key`

`-> help`

`-> label_help`

`-> placeholder`

Visibility on views

`-> show_on`

`-> hide_on`

`-> only_on`

`-> except_on`

`-> visible`

Formatting values

`-> format_using`

`-> format_{view}_using`

`-> update_using`

Form behavior

`-> required`

`-> disabled`

`-> readonly`

`-> default`

`-> nullable`

`-> null_values`

`-> autocomplete`

Index view

`-> sortable`

`-> summarizable`

`-> link_to_record`

Layout and rendering

`-> width`

`-> stacked`

`-> html`

`-> components`

`-> copyable`

Advanced

`-> for_attribute`

`-> meta`

`-> react_on`