TermUI.Widgets.FormBuilder (TermUI v0.2.0)

View Source

FormBuilder widget for structured forms with multiple field types.

Provides comprehensive form handling with validation, navigation, conditional fields, and field grouping.

Usage

FormBuilder.new(
  fields: [
    %{id: :username, type: :text, label: "Username", required: true},
    %{id: :password, type: :password, label: "Password", required: true},
    %{id: :remember, type: :checkbox, label: "Remember me"},
    %{id: :role, type: :select, label: "Role",
      options: [{"admin", "Admin"}, {"user", "User"}]}
  ],
  on_submit: fn values -> handle_submit(values) end,
  on_change: fn field_id, value -> handle_change(field_id, value) end
)

Field Types

  • :text - Single line text input
  • :password - Masked text input
  • :checkbox - Boolean toggle
  • :radio - Single selection from options
  • :select - Dropdown single selection
  • :multi_select - Multiple selection from options

Keyboard Navigation

  • Tab/Shift+Tab: Move between fields
  • Up/Down: Navigate options (radio/select/multi_select)
  • Space: Toggle checkbox, select option
  • Enter: Submit form (when on submit button)
  • Escape: Cancel editing

Summary

Types

field_def()
field_type()
group_def()

Functions

focus_field(state, field_id)

Focuses a specific field.

get_errors(state)

Gets all validation errors.

get_focused_field(state)

Gets the currently focused field.

get_value(state, field_id)

Gets the value of a specific field.

get_values(state)

Gets the current form values.

new(opts)

Creates new FormBuilder widget props.

reset(state)

Resets the form to initial values.

set_value(state, field_id, value)

Sets the value of a specific field.

set_values(state, values)

Sets multiple field values at once.

toggle_group(state, group_id)

Toggles a group's collapsed state.

valid?(state)

Checks if the form has any validation errors.

validate(state)

Validates all fields and returns updated state.

Types

field_def()

@type field_def() :: %{
  id: atom(),
  type: field_type(),
  label: String.t(),
  options: [{term(), String.t()}] | nil,
  required: boolean(),
  validators: [(term() -> :ok | {:error, String.t()})],
  visible_when: (map() -> boolean()) | nil,
  group: atom() | nil,
  placeholder: String.t() | nil,
  default: term() | nil
}

field_type()

@type field_type() :: :text | :password | :checkbox | :radio | :select | :multi_select

group_def()

@type group_def() :: %{id: atom(), label: String.t(), collapsible: boolean()}

Functions

focus_field(state, field_id)

@spec focus_field(map(), atom()) :: map()

Focuses a specific field.

get_errors(state)

@spec get_errors(map()) :: map()

Gets all validation errors.

get_focused_field(state)

@spec get_focused_field(map()) :: atom() | nil

Gets the currently focused field.

get_value(state, field_id)

@spec get_value(map(), atom()) :: term()

Gets the value of a specific field.

get_values(state)

@spec get_values(map()) :: map()

Gets the current form values.

new(opts)

@spec new(keyword()) :: map()

Creates new FormBuilder widget props.

Options

  • :fields - List of field definitions (required)
  • :groups - List of group definitions for organizing fields
  • :on_submit - Callback when form is submitted
  • :on_change - Callback when any field value changes
  • :values - Initial field values
  • :show_submit_button - Whether to show submit button (default: true)
  • :submit_label - Label for submit button (default: "Submit")
  • :validate_on_blur - Validate when field loses focus (default: true)

reset(state)

@spec reset(map()) :: map()

Resets the form to initial values.

set_value(state, field_id, value)

@spec set_value(map(), atom(), term()) :: map()

Sets the value of a specific field.

set_values(state, values)

@spec set_values(map(), map()) :: map()

Sets multiple field values at once.

toggle_group(state, group_id)

@spec toggle_group(map(), atom()) :: map()

Toggles a group's collapsed state.

valid?(state)

@spec valid?(map()) :: boolean()

Checks if the form has any validation errors.

validate(state)

@spec validate(map()) :: map()

Validates all fields and returns updated state.