# 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.

{% embed url="<https://youtu.be/JxpuQR4uxK0?si=9gNcoy0r7PF-7sU7>" %}

Watch this on Youtube: <https://www.youtube.com/watch?v=JxpuQR4uxK0>

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](https://docs.digia.tech/ui-building-blocks/widgets/default-properties "mention"):

**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.