PinCode

The PinCode widget provides a row of individual fields for entering a PIN or one-time password (OTP). Use it for flows such as account verification, sign-in, transaction confirmation, or device pairing.

You can retrieve the entered code and use it in actions or conditions. FlutterFlow stores this value in the PinCode widget's Widget State.

Handle Codes Securely

Do not expose PINs and OTPs outside the intended input and verification flow. Never include them in snackbars, logs, analytics, or error reports, and do not store them as plain text. Send the entered code to the relevant authentication provider or a secure backend for verification. A client-side comparison alone does not securely verify a code.

Adding a PinCode Widget

1. Open the Widget Palette and add the PinCode widget from Form Elements.
2. Select the widget and open the Properties Panel.
3. Under Pin Code Properties, set Pin Length to the number of characters users must enter. The maximum length is 8.
4. Choose a Keyboard Type that matches the expected code.

PinCode Events

The following events are available from the PinCode widget's Actions tab.

On Completed

On Completed runs when the number of entered characters reaches Pin Length. Use it to start a verification request, enable the next step, or update the interface.

This event only indicates that every field contains a value. It does not confirm that the entered code is valid.

On Change

On Change runs whenever a character is entered or deleted. Use it to update the interface as the value changes. See On Change for more information.

On Focus Change

On Focus Change runs when the PinCode widget gains or loses focus. Use it to update guidance or run validation when the user moves away from the widget. See On Focus Change for more information.

Validation

Validating a PIN or OTP involves three separate checks:

1. Check that the field is not empty.
2. Check that the code contains the required number of characters.
3. Check that the entered code is correct.

1. Require a Code

Use a Form to prevent users from submitting an empty PinCode field:

1. Place the PinCode widget inside a Form widget.
2. Select the Form and open Properties Panel > Validation.
3. Find the PinCode widget, enable its validation, and enter the error message to display when the field is empty.
4. Select the button or control that submits the code and open its Actions tab.
5. Add the Validate Form action. Under Select Form to Validate, choose the Form that contains the PinCode widget.

When the user submits the form without entering a code, FlutterFlow displays the error message.

2. Confirm the Code Is Complete

Before requesting verification, ensure that the user entered every character required by Pin Length. You can continue the flow from On Completed, or add a condition that checks whether the entered value contains the required number of characters.

3. Verify the Code

Send the complete value to your authentication provider or secure backend. Continue the flow only when that service confirms that the code is correct.

warning

Form validation only checks whether the PinCode field is empty. It does not confirm that every field is complete or that the PIN or OTP is correct.

Customizing

Select the PinCode widget and open Pin Code Properties in the Properties Panel.

Configuring Input

• Pin Length: Sets the number of characters in the code, up to 8.
• Keyboard Type: Uses a numeric keyboard by default. Select Visible Password when the code can contain letters and numbers. The keyboard layout can vary by platform.

Configuring the Entry Animation

• Animation: Selects the animation used when a character is entered, such as Slide.
• Animation Curve: Controls how the animation speeds up or slows down. Leave it Unset to use the default curve.
• Animation Duration (ms): Sets how long the animation takes in milliseconds.

Hiding Entered Characters

• Obscure Text: Replaces each entered character with the selected Obscuring Character.
• Obscuring Character: Selects the character used to hide the entered value.
• Blink When Obscuring: Adds a brief blink effect when a newly entered character is obscured.
• Blink Duration: Sets the duration of the obscuring blink in milliseconds.

Configuring Input Behavior

• Hint Text: Displays the selected Hint Character in each empty field.
• Hint Character: Selects the character displayed in empty fields when Hint Text is enabled.
• Auto Focus: Focuses the PinCode widget and opens the keyboard when the page loads. Disable it when another element should receive focus first.
• Auto Fill: Allows supported operating systems to suggest a received verification code. Availability depends on the platform, device settings, and message format.
• Read Only: Displays the PinCode value without allowing the user to edit it.
• Haptic Feedback: Provides haptic feedback on supported devices when the user enters a character.

Aligning the Fields

Use Pin Code Alignment to position the fields within the available width:

• Start: Places the fields at the beginning.
• Center: Centers the fields.
• End: Places the fields at the end.
• Space Evenly: Adds equal space before, between, and after the fields.
• Space Around: Adds space around each field, with smaller spaces at the beginning and end.
• Space Between: Places equal space between the fields without adding space at the beginning or end.

Changing Field Shape and Size

• Use Pin Field Shape to select Box, Circle, or Underline.
• Use Field Width and Field Height to set the dimensions of each field.
• When using Box, use Border Radius to round its corners and Border Width to adjust its outline.

Changing Colors, Fills, and Error Borders

Use the following properties to distinguish field states:

• Active Color: Sets the border color of a field that contains a value.
• Inactive Color: Sets the border color of an empty field.
• Selected Color: Sets the border color of the field that currently has focus.
• Background Color: Sets the background color of the overall PinCode widget, including the area around the individual fields.
• Enable Active Fill: Determines whether the background of pin fields containing input is filled. When enabled, the next three fill-color properties become available.
• Active Fill Color: Sets the fill color of a field that contains a value.
• Inactive Fill Color: Sets the fill color of an empty field.
• Selected Fill Color: Sets the fill color of the field that currently has focus.
• Error Text Height: Reserves vertical space for a validation error message.
• Error Border Width: Sets the width of the field border when validation fails.
• Error Border Color: Sets the field border color when validation fails.

Do not rely on color alone to communicate an error or status. Include clear text guidance or an error message.

Customizing the Cursor

Use Show Cursor to show or hide the text cursor and Cursor Color to change its color.

Styling the Entered Text

Expand Pin Code Text Style to change how entered characters appear:

• Theme Text Style: Starts with a text style from the project theme.
• Font Family: Selects the font used for entered characters.
• Font Weight: Controls the thickness of the characters.
• Styling: Applies italic, underline, or strikethrough formatting.
• Font Size: Sets the character size.
• Text Color: Sets the character color.
• Line Height: Controls the vertical spacing within each field.
• Letter Spacing: Adjusts the space around each character.
• Text Align: Aligns the character inside each field.
• Add Shadow: Adds and configures a shadow behind the characters.
• Text Overflow Replacement: Controls how a character is handled when it does not fit inside its field.

Accessing and Clearing the Value

To use the entered code in an action, select Set from Variable > Widget State, then choose the PinCode widget.

To clear the entered code, the PinCode widget must be inside a Form widget. You can then add the Reset Form Field action and select the PinCode widget. Clear sensitive values after verification and when the user requests a new code.

Best Practices

• Verify PINs and OTPs through the relevant authentication provider or a secure backend.
• Never expose sensitive codes in snackbars, logs, analytics, or error reports.
• Use Obscure Text when the code must remain private while it is entered.
• Use a numeric keyboard unless the code can contain letters.
• Provide clear instructions and validation messages, and do not rely on color alone.
• Prevent duplicate verification requests while an earlier request is still in progress.
• Clear the value after successful verification, after too many failed attempts, or when the code expires.