Reference

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

Note:: the Public API is what is referenced below. There may be additional functions marked as public within modules. These are for internal use and are subject to change. If you find yourself needing to use one of these functions, please open a GitHub issue so we can explore if there's a better solution or a way to surface it as a stable public function moving forward.

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.Renderer.LiveComponent (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