Form States

Because Flux uses HTMX to handle submissions, the user never experiences a full page reload. Instead, the form transitions dynamically between different visual states based on the result of the submission.

Understanding these states helps you design better integration and anticipate what your users will see.

1. Normal State (Ready)

This is the default state when the form first loads on your webpage.

• Appearance: All fields are visible, inputs are empty (or show their placeholders), and the submit button is ready.
• Behavior: When the user clicks "Submit," the browser sends the data to Flux. The form enters a "loading" state (if you have configured a loading indicator) while waiting for the server response.

2. Validation Error State (Correction)

If the user submits data that fails your server-side validation rules (e.g., an email domain is blocked, or a password is too short), Flux returns the form in the Validation Error State.

• Appearance:
  • The form reappears instantly.
  • Crucial: All user inputs are preserved. The user does not have to re-type their valid fields.
  • Inline Errors: Specific error messages (e.g., "Must be at least 10 characters") appear in red text immediately below the invalid fields.
  • Global Errors: If there is a general issue (like a Captcha failure), a summary banner may appear at the top.

3. System Error State (Failure)

This state occurs when a technical failure prevents the form from processing the request. This is distinct from a user validation error.

• Triggers:
  • The Flux database is "Sealed" (Locked).
  • A misconfiguration (e.g., the configured Captcha provider was deleted).
  • Critical server-side failure.
• Appearance: Instead of the form fields, the user sees a generic Error Block explaining that the request could not be processed.
• Note: This behavior is currently a Work In Progress (WIP) and may be refined in future updates.

4. Success State (Completion)

When the validation passes and the submission is securely recorded, Flux replaces the entire form with the Success State.

• Appearance: The form inputs disappear completely. They are replaced by a customizable "Thank You" message.
• Customization: You can define the text for this screen in the Form settings (see below).

Customizing State Messages

You can customize the text shown in the Success and Error states to match your brand's voice or language. This is done via the Dictionary settings in the TUI.

1. SSH into Flux: ssh -p 2222 admin@<host>
2. Navigate to Forms -> (Select Form) -> Edit Dictionary.

Available Keys

Example configuration:

• Success Title: "Message Sent!"
• Success Message: "Thanks for reaching out. Our team usually responds within 2 hours."