# PinField

The **Pin Field** widget is a **specialized input control** designed for entering short, fixed-length codes—usually **OTPs (One-Time Passwords)**, **PINs**, or **verification codes**.\
Instead of a single text box, it shows **multiple boxes**, one for each character, giving a clean and focused input experience.

{% embed url="<https://youtu.be/ezEUjBX98xA?si=qZbMkvuQUIk5zxww>" %}

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

#### Adding a PinField Widget

The PinField widget is located in the **Form Elements** section of the Widget Palette. Once added, you can configure its properties from the **Widget Properties Panel**.

<figure><img src="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-e8a8a7005cf2b8023b376089f4888743c26886d6%2Fpinfield.png?alt=media" alt="A hero image showing a pin field widget with multiple input boxes for secure code entry."><figcaption><p>The PinField widget provides secure, focused input for PINs and verification codes.</p></figcaption></figure>

### **Core Concepts**

* **Fixed Length Input**
  * Controlled using the `length` property.
  * Ensures users enter **exactly N characters** (e.g., 4, 6 digits).
* **Per-Box UI**
  * Each character appears in its **own box**.
  * Styling is controlled via **Pin Theme Properties**—so you can:
    * Match brand design
    * Highlight focus
    * Show subtle separators
* **Security & Privacy**
  * With `obscureText` and `obscureSymbol`, you can hide the actual characters:
    * Ideal for PINs and sensitive codes
    * Shows `*` or `•` instead of the real input
* **Guided Input Flow**
  * As users type, focus moves automatically to the **next box**.
  * `autoFocus` can focus the Pin Field immediately when the screen appears, making OTP flows feel fast.
* **Event-Driven**
  * `onChanged` fires on every character change → great for live validation or enabling/disabling buttons.
  * `onCompleted` fires when **all characters are filled** → perfect to auto-submit, verify code, or move to the next step.

### Properties

| Property        | Description                                                                                                                     |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `length`        | The total number of characters in the pin/OTP. For example, `4`, `6`, etc.                                                      |
| `enabled`       | If `false`, the Pin Field is disabled and cannot be interacted with (useful when waiting for an OTP resend or while verifying). |
| `autoFocus`     | If `true`, the Pin Field will automatically gain focus when the screen loads, so users can start typing immediately.            |
| `obscureText`   | If `true`, the entered characters are visually hidden (e.g., shown as `*` or `•`) for privacy and security.                     |
| `obscureSymbol` | The character used to obscure the input (like `*`, `•`, or any symbol you prefer).                                              |

#### Pin Theme Properties

These properties define the appearance of each individual character field in the pin input.

| Property       | Description                                 |
| -------------- | ------------------------------------------- |
| `width`        | The width of each pin field box.            |
| `height`       | The height of each pin field box.           |
| `margin`       | The margin around each pin field box.       |
| `padding`      | The padding within each pin field box.      |
| `textStyle`    | The TextStyle for the entered characters.   |
| `fillColor`    | The background color of each pin field box. |
| `borderColor`  | The border color of each pin field box.     |
| `borderWidth`  | The border width of each pin field box.     |
| `borderRadius` | The corner radius of each pin field box.    |

#### Events

| Property      | Description                                                                                                                                                                                                                                                             |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onChanged`   | Triggered whenever the user types, deletes, or changes any character. Receives an object with the current `pin` value showing what has been entered so far. Useful for live validation, enabling buttons when minimum length is reached, or reacting to partial input.  |
| `onCompleted` | Triggered when **all characters are filled** (i.e., input length equals `length`). Receives an object with the complete `pin` value for processing. Perfect for auto-submitting the code, calling a verify API, or moving to the next screen without extra button taps. |

### Default Properties

The Pin 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`

**Visible**

* `visible`

### **Use Cases**

You’ll typically use a **Pin Field** when:

* Verifying a user’s **phone number** or **email** via OTP
* Asking users to set or enter a **PIN** for login or sensitive actions
* Implementing **2FA / security code** inputs
* Handling **transaction confirmations** (payments, withdrawals, etc.)
* Any flow where a **short, fixed-length, high-focus code** is required

Why it’s better than a normal TextField:

* Easier to **see how many digits** are required
* More **visually secure** (with obscure mode)
* Feels like the familiar OTP input from banking & fintech apps.