Reference

Quick lookup tables. For narrative documentation see the Usage guide.

DynamicForm.form/1 attributes

Exactly one of instance, json, or <:field> slots must be provided. render_only excludes the lifecycle attributes (on_change, change_debounce_in_ms, on_submit, on_success, send_message_on, data, form_name, validation_summary) and file upload questions — both raise.

DynamicForm.RendererLive (used directly via <.live_component>) accepts id, instance, and the same optional attributes from data down.

<:field> attributes

Slot bodies: any question type accepts a body receiving its Phoenix.HTML.FormField via :let; html accepts a plain body; custom requires a body receiving the Phoenix form.

<:group> attributes

<:nested> attributes

Declares a repeating child form (→ a SurveyJS paneldynamic question); fields join it with <:field nested="...">. See the Nested Forms guide.

Question types

Element types

Validators

Data-mode JSON validator objects (built automatically by the flattened attrs in declarative mode). Each accepts a custom error message via text:

input_type="email" also applies email format validation automatically.

Conditional expression operators

Used by visible_if, required_if, and enable_if:

Field references use braces: {field_name}. Literals: 'strings', numbers, true/false, ['lists', 'of', 'values'].

Messages

Sent to the parent LiveView, carrying the lifecycle event and the payload:

{:dynamic_form, event, %DynamicForm.Payload{}}

A valid submission with all three enabled delivers :change, :submit, and :success, in that order. :change and :submit payloads are routinely invalid — check DynamicForm.Payload.valid?/1.

%DynamicForm.Payload{} fields:

Lifecycle callback contracts

on_change:  (DynamicForm.Payload.t()) -> DynamicForm.Payload.t()
on_submit:  (DynamicForm.Payload.t()) -> DynamicForm.Payload.t()
on_success: (DynamicForm.Payload.t()) -> any()

on_change runs after built-in validations, on every change (including a nested entry add/remove) and during the submit validation pass — after change_debounce_in_ms milliseconds of quiet when that attribute is set, except on submit, where it always runs inline. on_submit runs on every submit — valid or not — so it can batch expensive checks with the built-in errors into one complete error list. Both are validation hooks that run alongside the built-in behavior: reject a submission with DynamicForm.Payload.add_error/4 (validity lives on the changeset, so adding an error marks the submission invalid); perform side effects in the parent's handle_info/2 instead.

on_success runs on every valid submission and replaces the :success message; its return value is ignored. Listing :success in send_message_on alongside it raises.

Messages reach the LiveView process only. A LiveComponent parent uses the callbacks with Phoenix.LiveView.send_update/2 instead — see the Lifecycle guide.

Upload metadata keys

metadata map keys for type="file" questions:

Uploaded files are stored in the form data as maps with filename, cloud_bucket, cloud_path, cloud_provider, and uploaded_on.

Custom field types

Registered as %{"type_name" => ecto_type} via the :dynamic_form, :custom_field_types config and/or the custom_field_types attribute (per-form entries win). The Ecto type drives casting ({:array, _} types get checkbox-group-style param normalization); rendering dispatches to the components module's input/1, matched by a def input(%{type: "type_name"} = assigns) clause. Names colliding with built-in types raise. Unregistered question types render nothing.

Components contract

Functions the renderer dispatches through the components module (per-function fallback to DynamicForm.CoreComponents):

Helper functions