# 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](/ui-building-blocks/widgets/default-properties.md):

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digia.tech/ui-building-blocks/widgets/input-interaction-widgets/text-form-field.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.