Text Form Field

The Text Form Field widget is a versatile input field that lets users enter and edit text. It supports rich customization for appearance, validation, behavior, and events, making it suitable for everything from simple inputs to complex forms.

Whenever you need user-typed text with control over validation, styling, and interaction, this widget is the default choice.

Core Concepts

• Input Control

  • initialValue, controller, enabled, readOnly, autoFocus Let you control what the field shows, whether it’s editable, and when it gets focus.

• Input Behavior

  • obscureText, keyboardType, textInputAction, textAlign, minLines, maxLines Define how the user types (password vs normal, number vs email), how many lines it uses, and what the keyboard’s action button does.

• Visual Styling

  • Text, hint, label, fill color, cursor, padding + border properties for different states Control how the field looks in normal, focused, disabled, and error states.

• Validation & Errors

  • validationRules, regex, errorText, errorStyle Validate user input and show clear error messages when it’s invalid.

• Events & Debounce

  • onChanged, onSubmit, debounceValue React to user input and submissions, with optional debounced updates for things like search or live validation.

Properties

1. Preview Mode

Property	Description
Field State Preview	Preview the text field in different states (enabled, disabled, focused, error).

2. Content

Property	Description
Controller	An Text field controller variable to control the text field's value programmatically.
Initial Value	The initial text to display in the field.
Label Text	Text that "floats" above the field when it is focused.
Hint Text	Placeholder text to display when the field is empty.
Max Length	The maximum number of characters allowed in the field.
Min Lines	The minimum number of lines the field will occupy.
Max Lines	The maximum number of lines the field can expand to.

3. Behaviour

Property	Description
Read Only	If true, the text in the field cannot be modified by the user.
Obscure Text	If true, the entered text will be obscured (e.g., for passwords).
Auto Focus	If true, the text field will automatically be focused when the screen loads.
Enabled	If false, the text field is disabled.
Keyboard Type	The type of keyboard to display (e.g., text, number, emailAddress).
Text Input Action	The action to be performed when the user presses the "enter" or "done" key on the keyboard.
Text Align	The horizontal alignment of the text within the field.

4. Actions

Property	Description
Debounce Delay	The delay in milliseconds before the onChanged action is triggered.
onChanged	An action to trigger whenever the text in the field changes.
onSubmit	An action to trigger when the user submits the field (e.g., by pressing "done" on the keyboard).

5. Colors & Padding

Property	Description
Fill Color	The background color of the text field.
Focus Color	The color of the field when it is focused.
Cursor Color	The color of the blinking cursor.
Content Padding	The padding around the text within the field.

6. Borders

The Borders section includes a Border Type Preview and individual border styles for different states:

Border Types:

• Underline: Border style, border width, border color, border radius

• Outline: Border style, border width, border color, border radius

• Outline Dashed: Border style, border width, border color, border radius, stroke cap, dash pattern

• Underline Dashed: Border style, border width, border color, border radius, stroke cap, dash pattern

Border States:

• Enabled Border: The border style when the field is enabled

• Disabled Border: The border style when the field is disabled

• Focused Border: The border style when the field is focused

• Focused Error Border: The border style when the field is focused and has an error

• Error Border: The border style when the field has a validation error

7. Text Style

Property	Description
Content Text Style	The TextStyle for the text entered by the user.
Label Text Style	The TextStyle for the label text.
Hint Text Style	The TextStyle for the hint text.
Error Text Style	The TextStyle for the error text.

8. Validation Rules

Validation rules allow you to add multiple validation criteria. Each validation rule has:

Property	Description
Type	The type of validation: required, max length, min length, or pattern (regex).
Data	The validation data (e.g., max/min length value, regex pattern).
Error Message	The error message to display when the validation fails.

9. Prefix Icon Constraints

Property	Description
Min Width	The minimum width of the prefix icon container.
Max Width	The maximum width of the prefix icon container.
Min Height	The minimum height of the prefix icon container.
Max Height	The maximum height of the prefix icon container.

10. Suffix Icon Constraints

Property	Description
Min Width	The minimum width of the suffix icon container.
Max Width	The maximum width of the suffix icon container.
Min Height	The minimum height of the suffix icon container.
Max Height	The maximum height of the suffix icon container.

Children of Text Form Field

This is a leaf widget that does not support children.

Default Properties

The Text Form Field widget supports the following sections of Default Properties:

Layout

• width

• height

• padding

• margin

Alignment

• align

Visibility

• visible

Use Cases

You’ll typically use Text Form Field in:

• Forms & Authentication

  • Login / signup fields (email, password)

  • OTP backup input, username, phone number

  • Profile forms (name, address, bio)

• Search & Filters

  • Search bars for lists, products, or content

  • Filter inputs (e.g., min/max price, tags, keywords)

• Multi-Line Input

  • Feedback or support messages

  • Comments, notes, or descriptions

  • In-app messaging / short text content

• Validated Inputs

  • Email, phone, or custom format fields using regex

  • Inputs with min/max length, required fields, etc.