patternedinput 1.0.1

SDKflutter
Platformandroidioswindowslinuxmacosweb

A customizable Flutter widget for pattern-driven input fields with intelligent paste handling, auto-navigation, and validation. Perfect for OTP, form codes, and structured data entry.

Patterned Input

A customizable Flutter widget for creating pattern-driven input fields with intelligent paste handling, auto-navigation, and validation. Perfect for OTP codes, form numbers, license plates, and any structured data entry.

Features

  • 🎯 Pattern-Driven Input: Define input patterns using InputType.alpha, InputType.digit, or InputType.alphanumeric
  • 🔄 Intelligent Paste Handling: Smart character distribution with validation
  • 🎯 Auto-Navigation: Automatic focus management between fields
  • ✅ Real-time Validation: Prevent invalid characters and provide instant feedback
  • 🎨 Customizable UI: Full control over styling, spacing, and decoration
  • 📱 Controller Support: Programmatic access to widget state and methods

Installation

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

dependencies:
  patterned_input: ^1.0.0

Then run:

flutter pub get

Usage

Basic Example

import 'package:patterned_input/patterned_input.dart';

PatternedInput(
  pattern: [
    InputType.alpha,
    InputType.alpha,
    InputType.alpha,
    InputType.digit,
    InputType.digit,
    InputType.digit,
  ],
  onChanged: (value) => print('Current: $value'),
  onComplete: (value) => print('Complete: $value'),
)

USCIS Case Number Example

PatternedInput(
  pattern: [
    InputType.alpha, InputType.alpha, InputType.alpha, // ABC
    InputType.digit, InputType.digit, InputType.digit, // 123
    InputType.digit, InputType.digit, InputType.digit, // 456
    InputType.digit, InputType.digit, InputType.digit, // 789
    InputType.digit, // 0
  ],
  onComplete: (value) {
    // Handle complete USCIS case number (e.g., "ABC1234567890")
    print('USCIS Case Number: $value');
  },
)

With Controller

final controller = PatternedInputController();

PatternedInput(
  pattern: [InputType.digit, InputType.digit, InputType.digit, InputType.digit],
  controller: controller,
  onComplete: (value) => print('Complete: $value'),
)

// Programmatic control
controller.setValue('1234');
print('Current value: ${controller.value}');
print('Is valid: ${controller.isValid}');
controller.clear();

Customization

PatternedInput(
  pattern: [InputType.alpha, InputType.digit, InputType.alpha],
  fieldWidth: 50.0,
  fieldHeight: 50.0,
  spacing: 12.0,
  textStyle: TextStyle(
    fontSize: 20,
    fontWeight: FontWeight.bold,
    color: Colors.blue,
  ),
  decoration: InputDecoration(
    border: OutlineInputBorder(
      borderRadius: BorderRadius.circular(12),
    ),
    filled: true,
    fillColor: Colors.grey.shade100,
  ),
)

Input Types

InputTypeDescriptionValid Characters
InputType.alphaAlphabetic onlyA-Z (case insensitive, stored as uppercase)
InputType.digitNumeric only0-9
InputType.alphanumericBoth letters and numbersA-Z, 0-9

Properties

PropertyTypeDescriptionDefault
patternList<InputType>Defines the input patternRequired
onChangedValueChanged<String>?Called when any field changesnull
onCompleteValueChanged<String>?Called when all fields are fillednull
controllerPatternedInputController?Controller for programmatic accessnull
decorationInputDecoration?Custom decoration for fieldsDefault styling
textStyleTextStyle?Text style for input fieldsDefault styling
spacingdoubleSpacing between fields8.0
fieldWidthdoubleWidth of each field45.0
fieldHeightdoubleHeight of each field45.0
autoFocusboolAuto-focus first fieldtrue

Controller Methods

MethodDescription
String get valueGet current input value
bool get isValidCheck if all fields are filled
void clear()Clear all input fields
void setValue(String value)Set value programmatically
void focusField(int index)Focus specific field

Paste Handling

The widget intelligently handles paste operations:

  1. Smart Distribution: Characters are distributed across fields based on the pattern
  2. Validation: Only valid characters for each field type are accepted
  3. Boundary Respect: Pasting stops at pattern boundaries or invalid characters
  4. Focus Management: Automatically focuses the next appropriate field

Example: Pasting "ABC123XYZ" into a pattern [alpha, alpha, alpha, digit, digit, digit] will result in "ABC123" with focus on the next field.

Use Cases

  • OTP Verification: 4-6 digit verification codes
  • License Plates: Letter-number combinations
  • Government Forms: USCIS case numbers, SSN formatting
  • Product Codes: Mixed alphanumeric identifiers
  • Credit Card Numbers: Chunked numeric input
  • Postal Codes: Regional format validation

Example App

See the example/ directory for a complete sample app demonstrating various use cases and customization options.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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