Flutter OTP Kit #

Professional OTP Verification Package for Flutter

A comprehensive, production-ready Flutter package for OTP (One-Time Password) verification with extensive customization options, responsive design, robust error handling, RTL/LTR support, and intelligent focus management. Built with a modern widget-based architecture, this package offers unparalleled flexibility, maintainability, and performance.

📸 Screenshots & Demo #

Basic Design with Validation Error	Empty Initial Basic Design	Complete Filled Inputs
Email Basic Design	Widget Design While Writing	Complete Typed Widget Design

🎬 Video Demo #

Tutorial Video: Complete walkthrough of Flutter OTP Kit features and implementation

✨ Features #

🎯 Core Functionality #

• Complete OTP Verification: Full-featured OTP input with validation and verification
• Multiple Input Types: Numeric, alphabetic, alphanumeric, and custom input support
• Smart Paste Detection: Enhanced clipboard detection with debounce mechanism
• Consecutive Digit Support: Fixed issue preventing consecutive identical digits
• Real-time Validation: Live validation with custom regex patterns and error messages
• Auto-submit: Automatic form submission when OTP is complete
• Timer Integration: Enhanced timer with automatic start and proper reset on resend
• Smart Validation: Prevents verification with incomplete fields
• Instant Error Clearing: Validation errors clear immediately when user starts typing
• Backend Integration Ready: Perfect for Cubit/Bloc patterns with automatic state management
• Real-time State Callbacks: Custom widgets get notified of all state changes instantly

🎨 Design & Customization #

• Perfect Visual Hierarchy: Strict visual hierarchy: Error > Focused > Completed > Filled > Empty
• Generic Color System: All colors are completely customizable
• Comprehensive Styling: Complete control over colors, dimensions, spacing, and appearance
• Advanced Field Shapes: Rectangle, rounded rectangle, circle, stadium, and custom shapes
• Custom Border Styles: Solid, dashed, dotted, bottomOnly, topOnly, leftOnly, rightOnly
• Gradient Support: Linear, radial, and sweep gradient backgrounds
• Shadow Effects: Customizable shadows with color, blur, spread, and offset control
• Animation System: Smooth animations with professional transitions
• Theme Integration: Material Design 3, light, dark themes with automatic adaptation
• Responsive Design: Fixed pixel overflow issues with proper text wrapping

📱 Responsive & Layout #

• Responsive Design: Automatic adaptation to different screen sizes and orientations
• Single Row Layout: Standard OTP appearance with fields always in a single row
• Smart Spacing: Dynamic field spacing with min/max constraints and safety margins
• Overflow Protection: Comprehensive overflow prevention with multiple safety layers
• Cross-platform: Optimized for iOS, Android, Web, and Desktop

♿ Accessibility & UX #

• Screen Reader Support: Complete accessibility with semantic labels and hints
• Keyboard Navigation: Full keyboard navigation support
• Focus Management: Proper focus handling and auto-focus capabilities
• Haptic Feedback: Optional haptic feedback for better user experience
• Interactive Selection: Configurable text selection behavior
• Contact Masking: Automatic phone/email masking for privacy
• RTL/LTR Support: Complete right-to-left and left-to-right language support
• Auto Direction Detection: Automatic text direction detection based on app locale
• Tap Outside Unfocus: Global tap outside functionality to unfocus fields
• Intelligent Focus Management: Real-time focus state synchronization

🔧 Advanced Features #

• Custom Validators: Complete validation control with custom logic
• Input Formatters: Support for custom TextInputFormatter
• Biometric Input: Support for advanced input methods
• Voice Input: Voice input capabilities
• Swipe Navigation: Touch gesture support for field navigation
• Custom Field Builders: Complete control over field appearance and behavior
• Backend Integration: Built-in methods for Cubit/Bloc state management
• Automatic State Handling: Package handles all error/validation states automatically

🧩 Architecture #

• Widget-Based Design: Modular architecture for better maintainability
• State Management: Dedicated state management for OTP fields
• Styling System: Centralized styling for consistent appearance
• Configuration System: Comprehensive configuration options
• Utility Functions: Reusable utility functions for common tasks
• Public API: Clean and well-documented public API

📦 Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_otp_kit: ^2.2.0

Then run:

flutter pub get

🚀 Quick Start #

Basic Usage #

import 'package:flutter_otp_kit/flutter_otp_kit.dart';

OtpVerificationWidget(
  title: 'Verify Phone Number',
  subtitle: 'Enter the code sent to {contactInfo}',
  contactInfo: '+1 (555) 123-4567',
  maskingType: MaskingType.phone,
  onVerify: (otp) {
    // Handle OTP verification
    print('Verifying OTP: $otp');
  },
  onResend: () {
    // Handle resend OTP
    print('Resending OTP');
  },
)

Complete Field Configuration Control #

The package offers complete field configuration control through the fieldConfig parameter:

Method 1: Individual Parameters (Simple)

OtpVerificationWidget(
  fieldShape: OtpFieldShape.circle,
  fieldWidth: 50,
  fieldHeight: 50,
  borderWidth: 2.0,
  primaryColor: Colors.blue,
  onVerify: (otp) => handleVerification(otp),
  onResend: () => resendCode(),
)

Method 2: Complete Field Configuration (Advanced)

OtpVerificationWidget(
  title: 'Custom Styled OTP',
  subtitle: 'Enter the verification code',
  fieldConfig: OtpFieldConfig(
    // Field dimensions
    fieldWidth: 60,
    fieldHeight: 70,
    borderRadius: 15,
    borderWidth: 3,
    
    // Field shape and styling
    fieldShape: OtpFieldShape.custom,
    fieldShapeConfig: OtpFieldShapeConfig(
      borderStyle: OtpBorderStyle.dashed,
      dashPattern: [8, 4],
    ),
    
    // Colors
    primaryColor: Colors.purple,
    backgroundColor: Colors.purple.shade50,
    
    // Effects
    enableShadow: true,
    shadowColor: Colors.purple.withOpacity(0.3),
    focusEffect: FocusEffect.glow,
    completedEffect: CompletedEffect.fillAndBorder,
    
    // Typography
    fieldFontSize: 28,
    fieldFontWeight: FontWeight.bold,
    letterSpacing: 1.0,
    
    // Cursor
    cursorColor: Colors.purple,
    cursorWidth: 2.0,
    
    // Focus effects
    focusGlowRadius: 4.0,
    focusGlowIntensity: 0.8,
  ),
  onVerify: (otp) => handleVerification(otp),
  onResend: () => resendCode(),
)

🎨 Field Shapes & Styles #

Available Field Shapes #

• OtpFieldShape.rectangle - Square corners
• OtpFieldShape.roundedRectangle - Rounded corners
• OtpFieldShape.circle - Circular fields
• OtpFieldShape.stadium - Pill-shaped fields
• OtpFieldShape.underlined - Bottom border only
• OtpFieldShape.outlined - Material Design outlined
• OtpFieldShape.custom - Fully customizable

Custom Border Styles #

• OtpBorderStyle.solid - Solid border
• OtpBorderStyle.dashed - Dashed border
• OtpBorderStyle.dotted - Dotted border
• OtpBorderStyle.bottomOnly - Bottom border only
• OtpBorderStyle.topOnly - Top border only
• OtpBorderStyle.leftOnly - Left border only
• OtpBorderStyle.rightOnly - Right border only

📱 Platform Support #

Flutter OTP Kit is fully optimized for all Flutter-supported platforms:

Supported Platforms #

• Android - SDK 21+ with Material Design compliance
• iOS - iOS 12.0+ with Cupertino design guidelines
• Web - All modern browsers with responsive design
• Desktop - Windows, macOS, Linux with native keyboard navigation
• macOS - macOS 10.15+ with native styling

Platform-Specific Features #

Android

• Material Design 3 compliance
• Adaptive theming based on system theme
• Haptic feedback support
• Optimized for different screen densities
• Support for Android-specific input methods

iOS

• Cupertino design guidelines
• iOS-specific animations and transitions
• Support for iOS keyboard types
• Optimized for different iPhone and iPad sizes
• iOS-specific accessibility features

Web

• Responsive design for all screen sizes
• Touch and mouse input support
• Keyboard navigation optimized
• Web-specific performance optimizations
• Support for web-specific input methods

Desktop

• Native keyboard navigation
• Mouse and touchpad support
• Desktop-specific performance optimizations
• Support for desktop-specific input methods
• Multi-window support

Platform Adaptation Examples #

// Platform-adaptive styling
OtpVerificationWidget(
  title: 'Verify Phone Number',
  subtitle: 'Enter the code sent to {contactInfo}',
  contactInfo: '+1 (555) 123-4567',
  maskingType: MaskingType.phone,
  // Platform-adaptive field configuration
  fieldConfig: Platform.isIOS 
    ? OtpFieldConfig(
        fieldShape: OtpFieldShape.roundedRectangle,
        borderRadius: 12,
        borderWidth: 1.5,
        primaryColor: Colors.blue,
      )
    : OtpFieldConfig(
        fieldShape: OtpFieldShape.outlined,
        borderRadius: 8,
        borderWidth: 2,
        primaryColor: Colors.blue,
      ),
  onVerify: (otp) => handleVerification(otp),
  onResend: () => resendCode(),
)

🔧 Advanced Usage #

Backend Integration (Cubit/Bloc Ready) #

import 'package:flutter_otp_kit/flutter_otp_kit.dart';

final GlobalKey<OtpVerificationWidgetState> otpKey = GlobalKey();

OtpVerificationWidget(
  key: otpKey,
  title: 'Verify Phone Number',
  subtitle: 'Enter the code sent to {contactInfo}',
  contactInfo: '+1 (555) 123-4567',
  maskingType: MaskingType.phone,
  buttonText: 'Verify',
  resendText: 'Resend Code',
  timerPrefix: 'in',
  enableAutoValidation: true,
  onVerify: (otp) {
    // Your business logic
    if (otp == '1234') {
      // Success - package handles state automatically
      otpKey.currentState?.handleVerificationResult(true);
    } else {
      // Error - package handles state automatically
      otpKey.currentState?.handleVerificationResult(
        false, 
        errorMessage: 'Invalid OTP. Please try again.'
      );
    }
  },
  onResend: () {
    // Your resend logic
    print('Resending OTP');
  },
  // Real-time state callbacks for custom widgets
  onTimerChanged: (remainingTime) {
    // Custom widgets get notified of timer changes
    setState(() { _customTimer = remainingTime; });
  },
  onErrorStateChangedCallback: (hasError) {
    // Custom widgets get notified of error state changes
    print('Error state changed: $hasError');
  },
  onValidationStateChanged: (isValidating) {
    // Custom widgets get notified of validation state changes
    print('Validation state changed: $isValidating');
  },
  onCompletionStateChanged: (isComplete) {
    // Custom widgets get notified of completion state changes
    print('Completion state changed: $isComplete');
  },
)

RTL/LTR Support #

// Automatic direction detection based on app locale
OtpVerificationWidget(
  title: 'تحقق من رقم الهاتف', // Arabic title
  subtitle: 'أدخل الرمز المرسل إلى {contactInfo}', // Arabic subtitle
  contactInfo: '+966501234567',
  maskingType: MaskingType.phone,
  buttonText: 'تحقق', // Arabic button text
  resendText: 'إعادة إرسال الرمز', // Arabic resend text
  timerPrefix: 'بعد', // Arabic timer prefix
  // textDirection: TextDirection.rtl, // Optional: Force RTL
  onVerify: (otp) {
    // Handle OTP verification
    print('Verifying OTP: $otp');
  },
  onResend: () {
    // Handle resend OTP
    print('Resending OTP');
  },
)

// Manual direction override
OtpVerificationWidget(
  title: 'Verify Phone Number',
  subtitle: 'Enter the code sent to {contactInfo}',
  contactInfo: '+1 (555) 123-4567',
  textDirection: TextDirection.ltr, // Force LTR
  onVerify: (otp) => handleVerification(otp),
  onResend: () => handleResend(),
)

Tap Outside Unfocus #

// Package handles tap outside automatically
OtpVerificationWidget(
  title: 'Verify Phone Number',
  subtitle: 'Enter the code sent to {contactInfo}',
  contactInfo: '+1 (555) 123-4567',
  unfocusOnTapOutside: true, // Enable global tap outside unfocus
  onVerify: (otp) => handleVerification(otp),
  onResend: () => handleResend(),
)

// External handler with priority
final GlobalKey<OtpVerificationWidgetState> otpKey = GlobalKey();

OtpVerificationWidget(
  key: otpKey,
  title: 'Verify Phone Number',
  subtitle: 'Enter the code sent to {contactInfo}',
  contactInfo: '+1 (555) 123-4567',
  unfocusOnTapOutside: true, // Package would handle it, but external handler takes priority
  externalTapOutsideHandler: () {
    // Your custom tap outside logic
    otpKey.currentState?.unfocusAllFields();
    // Additional custom logic here
  },
  onVerify: (otp) => handleVerification(otp),
  onResend: () => handleResend(),
)

Validation & Error Handling #

OtpVerificationWidget(
  title: 'Verify Phone Number',
  subtitle: 'Enter the code sent to {contactInfo}',
  contactInfo: '+1 (555) 123-4567',
  buttonText: 'Verify',
  resendText: 'Resend Code',
  timerPrefix: 'in',
  enableAutoValidation: true, // Prevents verify with incomplete fields
  validationMessage: 'Please enter all digits', // Shows when fields are missing
  onVerify: (otp) {
    if (otp == '1234') {
      // Success - proceed with verification
      print('Verification successful');
    } else {
      // Error - set error state programmatically
      otpKey.currentState?.setErrorState(true);
    }
  },
  onResend: () => resendOtp(),
)

Validation Features:

• ✅ Prevents incomplete verification: Verify button won't work with missing fields
• ✅ User-friendly messages: Shows "Please enter all digits" when fields are incomplete
• ✅ Instant error clearing: Validation errors disappear immediately when typing
• ✅ Programmatic control: Set/clear error states programmatically
• ✅ Smart error handling: Errors clear automatically on user interaction

🔧 Public Methods #

handleVerificationResult(bool, {String?}) #

Automatically handles verification results with comprehensive state management.

final GlobalKey<OtpVerificationWidgetState> otpKey = GlobalKey();

// Success - clears all error states automatically
otpKey.currentState?.handleVerificationResult(true);

// Error - sets error state and message automatically
otpKey.currentState?.handleVerificationResult(
  false, 
  errorMessage: 'Invalid OTP. Please try again.'
);

handleBackendState({bool?, bool?, String?, bool?, String?}) #

Comprehensive backend integration for Cubit/Bloc patterns.

final GlobalKey<OtpVerificationWidgetState> otpKey = GlobalKey();

// Loading state
otpKey.currentState?.handleBackendState(isLoading: true);

// Success state
otpKey.currentState?.handleBackendState(
  isLoading: false,
  hasError: false,
);

// Error state
otpKey.currentState?.handleBackendState(
  isLoading: false,
  hasError: true,
  errorMessage: 'Backend error message',
);

// Validation state
otpKey.currentState?.handleBackendState(
  isValidating: true,
  validationMessage: 'Custom validation message',
);

triggerResend() #

Public method to trigger resend functionality programmatically.

final GlobalKey<OtpVerificationWidgetState> otpKey = GlobalKey();

// Trigger resend programmatically
otpKey.currentState?.triggerResend();

clearOtp() #

Clears all OTP input fields with configurable options.

final GlobalKey<OtpVerificationWidgetState> otpKey = GlobalKey();

// Basic usage
otpKey.currentState?.clearOtp();

// Advanced usage with options
otpKey.currentState?.clearOtp(
  refocus: true,      // Whether to refocus first field
  clearError: true,   // Whether to clear error state
  callOnChanged: true // Whether to call onChanged callback
);

setOtp(String) #

Pre-fills fields with provided OTP with configurable options.

final GlobalKey<OtpVerificationWidgetState> otpKey = GlobalKey();

// Basic usage
otpKey.currentState?.setOtp('12345');

// Advanced usage with options
otpKey.currentState?.setOtp('12345',
  clearFocus: true,   // Whether to clear focus from all fields
  clearError: true,   // Whether to clear error state
  callCallbacks: true // Whether to call onChanged and onCompleted callbacks
);

getCurrentOtp() #

Returns the current OTP value.

final GlobalKey<OtpVerificationWidgetState> otpKey = GlobalKey();

// Get current OTP
String currentOtp = otpKey.currentState?.getCurrentOtp() ?? '';
print('Current OTP: $currentOtp');

setErrorState(bool) #

Sets the error state programmatically.

final GlobalKey<OtpVerificationWidgetState> otpKey = GlobalKey();

// Set error state
otpKey.currentState?.setErrorState(true);

clearErrorState() #

Clears the error state programmatically.

final GlobalKey<OtpVerificationWidgetState> otpKey = GlobalKey();

// Clear error state
otpKey.currentState?.clearErrorState();

isOtpValid() #

Checks if the current OTP is valid (complete and passes validation).

final GlobalKey<OtpVerificationWidgetState> otpKey = GlobalKey();

// Check if OTP is valid
bool isValid = otpKey.currentState?.isOtpValid() ?? false;

// Use in conditional logic
if (otpKey.currentState?.isOtpValid() ?? false) {
  // OTP is valid, proceed with verification
} else {
  // OTP is invalid, show error
}

📋 API Reference #

Required Parameters #

Optional Text Parameters (with defaults) #

Optional Parameters #

Field Configuration Parameters #

When using the fieldConfig parameter, you have access to all OtpFieldConfig properties:

🏗️ Architecture #

Flutter OTP Kit is built with a modern widget-based architecture that emphasizes separation of concerns, maintainability, and flexibility. This architecture makes the package highly customizable, easy to extend, and simple to integrate into any Flutter application.

Widgets #

The package is organized into several key widgets, each with a specific responsibility:

OtpVerificationWidget

The main widget that orchestrates all widgets. It serves as the entry point for the package and manages the overall state and behavior of the OTP verification process.

OtpField

Individual OTP input field with customizable styling and behavior. Each field manages its own state, styling, and input handling.

OtpFieldsRow

Container for OTP fields that manages layout, spacing, and field arrangement. Supports different layout types (fixed, responsive) and handles overflow protection.

OtpHeader

Title and subtitle widget with support for masked contact information. Can be customized with widgets or strings.

OtpFooter

Verify button, resend button, and timer widget. Manages loading states, timer countdown, and button styling.

OtpErrorDisplay

Error message display widget that can be customized with widgets or strings.

State Management #

State management is centralized in dedicated classes that handle all aspects of OTP state, error state, and field state transitions.

OtpStateManager

Centralized state management for the OTP verification process. Handles field state transitions, error state management, focus management, and input handling.

OtpFieldState

Enum that represents the state of an OTP field. Used for styling and behavior.

ErrorStateBehavior

Enum that defines how error states should behave.

Styling #

Styling is managed by dedicated classes that handle all aspects of OTP field appearance based on state.

OtpStyleManager

Manages styling for OTP fields based on state, configuration, and theme. Provides consistent styling across all fields.

FieldColors

Represents the colors for an OTP field based on its state. Includes border color, background color, and text color.

Configuration #

Configuration is split into logical modules that handle specific aspects of the OTP verification process.

OtpFieldConfig

Configuration for OTP field appearance and behavior. Defines field dimensions, border properties, colors, and other visual aspects.

OtpErrorConfig

Configuration for error state behavior and appearance. Defines error state duration, auto-clear behavior, priority, and styling.

OtpAnimationConfig

Configuration for animations. Defines animation duration, curves, and behavior.

Utilities #

Utility classes provide reusable functionality for common tasks in the OTP verification process.

OtpMasker

Utilities for masking contact information (phone numbers, email addresses) for privacy.

OtpValidator

Utilities for validating OTP input based on input type, length, and custom rules.

OtpFormatter

Utilities for formatting OTP input, including input formatters and keyboard type.

🧪 Testing #

The package has been thoroughly tested across all platforms:

• Android: Tested on Android 5.0+ (API 21+) across different screen sizes
• iOS: Tested on iOS 12.0+ across iPhone and iPad devices
• Web: Tested on Chrome, Firefox, Safari, and Edge
• Desktop: Tested on Windows 10+, macOS 10.15+, and Linux
• Responsive: Tested across different screen sizes and orientations

📝 License #

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing #

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📞 Support #

If you encounter any issues or have questions, please:

1. Check the documentation
2. Search existing issues
3. Create a new issue if needed

🙏 Acknowledgments #

• Flutter team for the amazing framework
• Material Design team for design guidelines
• Cupertino team for iOS design guidelines
• All contributors and users of this package