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

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


---

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