OTP / PIN Input — OutSystems Forge Documentation

📋 Table of Contents

1. Overview & Description
2. Installation Guide
3. Component Properties Reference
4. Usage Examples
5. Troubleshooting Guide

1. Overview & Description <a name="overview"></a>

What is OTP Input?

OTP Input is a fully client-side Reactive Web Block for OutSystems that provides a professional, mobile-friendly One Time Password (OTP) or PIN input experience. It renders individual input boxes for each digit, handles auto-focus movement between boxes, supports paste, backspace navigation, error states, and fires an OutSystems event when the OTP is complete.

No external libraries required built entirely with vanilla JavaScript and OutSystems Reactive Web.

Key Features

• ✅ Configurable digit length (4, 6, or any number)
• ✅ Numbers only input with strict validation
• ✅ Auto moves focus to next box on digit entry
• ✅ Backspace moves focus to previous box
• ✅ Paste support — fills all boxes at once
• ✅ Auto submit when all boxes are filled
• ✅ Manual submit button option
• ✅ Error state with shake animation
• ✅ Fully customizable colors, size and spacing
• ✅ Mask input support (like password field)
• ✅ Fires OutSystems event to parent screen on completion
• ✅ Exposes WidgetId to parent via event for full control
• ✅ Clear and Reset actions
• ✅ Mobile keyboard optimized (numeric keypad)
• ✅ No external libraries or CDN required

Supported Platforms

Dependencies

2. Installation Guide <a name="installation"></a>

Step 1 — Download from Forge

1. Go to OutSystems Forge
2. Search for OTP Input
3. Click Install → Select your environment
4. Wait for installation to complete

Step 2 — Add Reference in Your Application

1. Open your Reactive Web Module in Service Studio
2. Go to Manage Dependencies (Ctrl+Q)
3. Search for OTPInputLib
4. Select and add the following:

5. Click Apply

Step 3 — Add Local Variables on Your Screen

Before placing the block, add these Local Variables on your screen:

Step 4 — Initialize OTPConfig Variable

In your screen's On Initialize event add an Assign node:

OTPConfig.Length             = 6
OTPConfig.AutoSubmit         = True
OTPConfig.ShowSubmitButton   = False
OTPConfig.InputSize          = 48
OTPConfig.SpacingBetween     = 8
OTPConfig.FontSize           = 20
OTPConfig.BorderColor        = "#CCCCCC"
OTPConfig.ActiveBorderColor  = "#0057D9"
OTPConfig.FilledBorderColor  = "#00A86B"
OTPConfig.ErrorBorderColor   = "#E8173A"
OTPConfig.Placeholder        = "·"
OTPConfig.MaskInput          = False
OTPConfig.IsError            = False

Step 5 — Add Block to Screen

1. Open the screen where you want the OTP input
2. In the widget toolbox find OTPInput under UI Flows
3. Drag it onto your screen
4. Set the Config input parameter to OTPConfig

Step 6 — Wire the Events

Wire SendContainerIDOnReady:

1. Click on the OTPInput block
2. Find SendContainerIDOnReady event in properties
3. Set it to New Client Action → name it OTPReady
4. Inside OTPReady add Assign:

OTPWidgetId = WidgetId

Wire OnOTPComplete:

1. Click on the OTPInput block
2. Find OnOTPComplete event in properties
3. Set it to New Client Action → name it OTPCompleted
4. Inside OTPCompleted add Assign:

EnteredOTP = OTPValue

5. After the assign — call your verify logic

Step 7 — Publish and Test

1. Press Ctrl+P to publish
2. Open app in browser
3. OTP boxes should appear and be ready for input

3. Component Properties Reference <a name="properties"></a>

Web Block: OTPInput

Events: OTPInput

Structure: OTPConfig

Client Actions

GetOTPValue

Returns the current OTP value from all boxes.

ClearOTP

Clears all boxes and focuses the first box.

SetOTPError

Sets all boxes to error state (red border + shake animation).

4. Usage Examples <a name="usage"></a>

Example 1 — Basic 6 Digit OTP with Auto Submit

OTPInput Block
  Config:
    Length            = 6
    AutoSubmit        = True
    ShowSubmitButton  = False
    InputSize         = 48
    BorderColor       = "#CCCCCC"
    ActiveBorderColor = "#0057D9"
    FilledBorderColor = "#00A86B"
    ErrorBorderColor  = "#E8173A"

Events:
  SendContainerIDOnReady → OTPReady
    └── OTPWidgetId = WidgetId

  OnOTPComplete → OTPCompleted
    └── EnteredOTP = OTPValue
        └── Call VerifyOTP server action

Example 2 — 4 Digit PIN with Manual Submit Button

OTPInput Block
  Config:
    Length           = 4
    AutoSubmit       = False
    ShowSubmitButton = True
    MaskInput        = True   ← Hides digits like password
    InputSize        = 52
    FontSize         = 24

User fills 4 boxes → clicks Verify OTP button → OnOTPComplete fires.

Example 3 — Full Verification Flow with Error Handling

OTPCompleted Client Action
  ├── Input: OTPValue (Text)
  │
  ├── Assign: EnteredOTP = OTPValue
  │
  ├── Server Action: VerifyOTP
  │     ├── Input:  OTPCode = EnteredOTP
  │     └── Output: IsValid (Boolean)
  │
  └── If IsValid = True
  │     └── Navigate to Success Screen
  │
  └── If IsValid = False
        └── SetOTPError
              ├── WidgetId         = OTPWidgetId
              ├── IsError          = True
              └── ErrorBorderColor = "#E8173A"

Example 4 — Resend OTP with Clear

Resend OTP Button → OnClick
  ├── Server Action: ResendOTP
  │
  └── ClearOTP
        ├── WidgetId    = OTPWidgetId
        └── BorderColor = "#CCCCCC"

Example 5 — Reset Error State After User Starts Typing

To clear the error state when user starts entering again:

OTPCompleted Client Action
  └── SetOTPError
        ├── WidgetId          = OTPWidgetId
        ├── IsError           = False
        └── DefaultBorderColor = "#CCCCCC"

Example 6 — Custom Branded OTP Boxes

OTPInput Block
  Config:
    Length            = 6
    InputSize         = 56
    FontSize          = 24
    SpacingBetween    = 12
    BorderColor       = "#E0E0E0"
    ActiveBorderColor = "#6200EE"   ← Purple active
    FilledBorderColor = "#03DAC6"   ← Teal filled
    ErrorBorderColor  = "#B00020"   ← Dark red error
    Placeholder       = "_"

5. Troubleshooting Guide <a name="troubleshooting"></a>

❌ Issue: OTP Boxes Showing Vertically

Cause: OutSystems container default is display: block

Fix:

1. Click OTPContainer widget inside the block
2. Set inline Style property to:

display: flex; flex-direction: row; gap: 8px; justify-content: center; align-items: center;

❌ Issue: OnOTPComplete Event Not Firing

Cause: Hidden trigger button not found in DOM

Fix:

1. Click OTPTriggerBtn hidden button in the block
2. Make sure Style property is set to:

opacity: 0; position: absolute; width: 0; height: 0; overflow: hidden; pointer-events: none;

3. Do NOT use display: none — it removes the button from DOM

❌ Issue: OTPWidgetId is Empty on Parent Screen

Cause: SendContainerIDOnReady event not wired correctly

Fix:

1. Click OTPInput block on screen
2. Find SendContainerIDOnReady in properties
3. Make sure it points to a Client Action that assigns:

OTPWidgetId = WidgetId

❌ Issue: ClearOTP or SetOTPError Not Working

Cause: OTPWidgetId is empty when action is called

Fix:

1. Make sure SendContainerIDOnReady is wired (see above)
2. Add a console log to verify:

console.log("OTPWidgetId:", $parameters.WidgetId);

3. Check it prints a value like b1-OTPContainer

❌ Issue: Paste Not Working on Mobile

Cause: Some mobile browsers handle clipboard differently

Fix:This is a browser limitation on some mobile devices. Workaround — user can long press → paste on the first box and it will fill all boxes automatically.

❌ Issue: Numbers Not Restricting — Letters Can Be Typed

Cause: JS keydown prevention not working on some mobile keyboards

Fix:Mobile keyboards fire events differently. The JS already handles this via:

var val = this.value.replace(/[^0-9]/g, "");

This strips non-numeric characters even if they get through the keydown check.

❌ Issue: Config Values Not Applied (Wrong Length/Colors)

Cause: Structure attributes come as empty/zero when not set — not as default values

Fix:Always initialize OTPConfig in screen's On Initialize event:

OTPConfig.Length = 6
OTPConfig.BorderColor = "#CCCCCC"
... (all attributes)

Never rely on structure default values alone.

❌ Issue: Multiple OTP Blocks on Same Screen Conflict

Cause: Both blocks share similar IDs

Fix:Currently the component is designed for one OTP block per screen. For multiple instances, contact the author for the multi-instance version.

💡 General Tips

• Always initialize all OTPConfig attributes in On Initialize — never leave them empty
• Use MaskInput = True for PIN entry screens
• Use ErrorLevel = "H" — not applicable here, use IsError = True for error state
• Test on actual mobile device — numeric keyboard shows automatically due to inputmode="numeric"
• AutoSubmit = True with ShowSubmitButton = False gives the smoothest UX for OTP flows
• AutoSubmit = False with ShowSubmitButton = True is better for PIN entry where user confirms manually

Documentation Version: 1.0.0Component Version: 1.0.0Last Updated: 2026Author: — (your name here)