Forms API

Per-attribute and per-method reference for forms. For task-oriented documentation and worked examples, see the Forms guide.

Every form is a class that inherits from Avo::Forms::Core::Form and lives under app/avo/forms/:

class Avo::Forms::AppSettings < Avo::Forms::Core::Form
  self.title = "Application Settings"

  def fields
    # field declarations
  end

  def handle
    # submission logic
  end
end

Class attributes

-> self.title

The display title for the form. When the form is rendered on a page, it appears as the header above the fields unless that placement sets show_header: false.

self.title = "Application Settings"

• Type: String
• Default: nil

-> self.description

A description rendered below the title in the form header.

self.description = "Manage your application configuration"

• Type: String
• Default: nil

-> self.id

The routing key — and URL segment — for the form. Forms are submitted to <root_path>/forms/<id> and resolved by their id at request time, so no routes are declared manually.

self.id = :app_settings

• Type: Symbol or String
• Default: the class path under Avo::Forms, e.g. Avo::Forms::Settings::Integrations → settings/integrations. A form declared inline under a page resolves against its page path instead.
• Constraint: must be unique across all forms — it's how a submission is matched to a form.

Form methods

-> fields

Defines the form's structure. Uses the same field syntax as Avo resources and actions, so it supports every Avo field type, panels and cards, and layout components.

def fields
  field :email, as: :text, required: true
  field :notifications, as: :boolean, default: true
end

• Type: instance method you define
• Returns: ignored — declare fields for their side effect, as in resources

-> field

Declares a single field inside fields. Accepts all standard Avo field types and field options.

field :theme, as: :select, options: { light: "Light", dark: "Dark" }

• Type: DSL method called inside fields
• Values: any Avo field type via as:; all standard field options are supported (required:, default:, help_text:, width:, record:, …)

-> handle

Processes the submission and defines the response. Called when the form is submitted, with submitted data available through params.

def handle
  current_user.update(params.permit(:first_name, :last_name))
  flash[:notice] = "Saved"
  default_response
end

• Type: instance method you define
• Context: evaluated in the controller that received the request, so any controller helper (params, current_user, flash, cookies, redirect_to, …) is available.
• Helpers: default_response — the standard redirect-back Turbo Stream response.

Experimental

handle runs in the controller's context rather than behind a dedicated DSL. This keeps the full Rails toolbox available, but the exact contract may change in a future release.