FormBuilder

Pre-populating values

Call SetValues(map[string]any) on the built form to set initial field values programmatically — useful when editing an existing record.

Relationship to Form

FormBuilder is a convenience layer over Form. All key bindings, submission, and cancellation behavior are the same — see the Form docs for the full reference.

catppuccin-frappecatppuccin-lattecatppuccin-macchiatocatppuccin-mochadraculadracula-lighteverforest-darkeverforest-lightgithub-darkgithub-lightgruvbox-darkgruvbox-lightkanagawamonokainordonedarkonelightrosepinerosepine-dawnrosepine-moonsolarized-darksolarized-lighttokyonight-daytokyonight-moontokyonight-nighttokyonight-storm

FormBuilder provides a fluent API for building forms.

Constructor func NewFormBuilder() *FormBuilder

Usage

form := components.NewFormBuilder().
  Text("name", "Name").
  Placeholder("Enter your name").
  Validate(validators.Required()).
  Done().
  Text("email", "Email").
  Validate(validators.Required(), validators.Email()).
  Done().
  Checkbox("notify", "Email notifications").
  Checked(true).
  Done().
  OnSubmit(func(values map[string]any) {
    name := values["name"].(string)
    email := values["email"].(string)
    notify := values["notify"].(bool)
    fmt.Printf("Name: %s, Email: %s, Notify: %v\n", name, email, notify)
  }).
  Build()

fmt.Println(form != nil)

Methods

Method	Signature	Description
AddField	func (fb *FormBuilder) AddField(field FormField) *FormBuilder	AddField adds a pre-built field directly to the form.
AsConfirmModal	func (fb *FormBuilder) AsConfirmModal(title string, width, height int) *Modal	AsConfirmModal creates a modal that dismisses on Escape.
AsFormModal	func (fb *FormBuilder) AsFormModal(title string, width, height int) *Modal	AsFormModal creates a modal that does NOT dismiss on Escape (to prevent data loss).
AsModal	func (fb *FormBuilder) AsModal(title string, width, height int) *Modal	AsModal wraps the form in a modal and returns it.
Build	func (fb *FormBuilder) Build() *Form	Build creates the final Form with all configured fields.
Checkbox	func (fb *FormBuilder) Checkbox(name, label string) *CheckboxBuilder	Checkbox adds a checkbox field and returns a builder to configure it.
Custom	func (fb *FormBuilder) Custom(name, typeName, label string) *CustomFieldBuilder	Custom adds a custom field type by its registered name. The field type must be registered with RegisterFormFieldType first.
MultiSelect	func (fb *FormBuilder) MultiSelect(name, label string, options []string) *MultiSelectBuilder	MultiSelect adds a multi-select field and returns a builder to configure it.
MultiSelectWithValues	func (fb *FormBuilder) MultiSelectWithValues(name, label string, options []SelectOption) *MultiSelectBuilder	MultiSelectWithValues adds a multi-select with custom label/value pairs.
OnCancel	func (fb *FormBuilder) OnCancel(fn func()) *FormBuilder	OnCancel sets the form cancellation callback.
OnSubmit	func (fb *FormBuilder) OnSubmit(fn func(values map[string]any)) *FormBuilder	OnSubmit sets the form submission callback.
Password	func (fb *FormBuilder) Password(name, label string) *TextFieldBuilder	Password adds a password field (masked text input) and returns a builder to configure it.
Radio	func (fb *FormBuilder) Radio(name, label string, options []string) *RadioGroupBuilder	Radio adds a radio group and returns a builder to configure it.
Select	func (fb *FormBuilder) Select(name, label string, options []string) *SelectBuilder	Select adds a select dropdown and returns a builder to configure it.
SelectWithValues	func (fb *FormBuilder) SelectWithValues(name, label string, options []SelectOption) *SelectBuilder	SelectWithValues adds a select dropdown with custom label/value pairs.
Text	func (fb *FormBuilder) Text(name, label string) *TextFieldBuilder	Text adds a text field and returns a builder to configure it.
TextArea	func (fb *FormBuilder) TextArea(name, label string) *TextAreaBuilder	TextArea adds a text area field and returns a builder to configure it.

Types

type Checkbox Checkbox is a boolean toggle component. It implements ValueProvider[bool].

type CheckboxBuilder CheckboxBuilder builds a Checkbox with fluent API.

type CustomFieldBuilder CustomFieldBuilder builds a custom field type.

type Form Form is a container for form fields with focus management.

type FormField FormField is the interface for form fields. Implementations expose their value through the polymorphic SetFieldValue / FieldValue / ClearField trio so the Form container does not need to know the concrete field type.

type Modal Modal is a configurable modal dialog with centered positioning. Modal implements the nav.ModalComponent interface for automatic lifecycle management.

type MultiSelect MultiSelect allows multiple option selection. It implements MultiValueProvider[string].

type MultiSelectBuilder MultiSelectBuilder builds a MultiSelect with fluent API.

type RadioGroupBuilder RadioGroupBuilder builds a RadioGroup with fluent API.

type Select Select is a dropdown selection component. It implements IndexedValueProvider[string].

type SelectBuilder SelectBuilder builds a Select with fluent API.

type SelectOption struct SelectOption represents an option in a select dropdown.

Field	Type	Description
Label	string
Value	string

type TextArea TextArea is a multi-line text input. It implements ValueProvider[string].

type TextAreaBuilder TextAreaBuilder builds a TextArea with fluent API.

type TextFieldBuilder TextFieldBuilder builds a TextField with fluent API.