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.

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.

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. 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). 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 section of Default Properties:

Layout

• width

• height

• padding

• margin

• align