Features ✨ #

• Accessibility (Semantics): Full screen reader support with semanticLabel parameter
  • Announces field purpose (e.g., "6-digit PIN code field")
  • Provides hints about remaining digits
  • Masks values when obscured for privacy
  • Exposes enabled/focused states
• cursorAlignment: Position custom cursor widgets within cells (e.g., underscore at bottom)

  MaterialPinTheme(
    cursorAlignment: Alignment.bottomCenter,
    cursorWidget: myUnderscoreCursor,
  )
  

• onClipboardFound: Callback when clipboard contains valid PIN-like content on focus
• onTapOutside: Callback when user taps outside the field
• errorText & errorBuilder: Custom error display below the PIN field
• followingFillColor & followingBorderColor: Style for cells after the focused cell
• completeFillColor, completeBorderColor & completeTextStyle: Style when all cells are filled

Bug Fixes 🐛 #

• Focus on complete: Last cell now shows focused state when PIN is complete and field is focused
• Cursor alignment: Fixed custom cursor positioning - removed internal Center widget that was overriding alignment
• Web input: Fixed text input not working on web by adjusting invisible text field configuration
• Controller notifications: Fixed PinInputController not notifying listeners on focus/text changes

Example App 📱 #

• Added comprehensive use case demos (OTP verification, PIN setup, PIN login, payment confirmation, invite codes, app lock screen)
• Added feature demos for all customization options:
  • Quick Start: Basic usage, Controller demo
  • Shapes & Themes: Shape gallery, Color customization, Shadows & elevation
  • Animations: Entry animations, Custom cursor
  • State Theming: All states demo, Error handling
  • Customization: Headless builder, Hints, Obscure text, Separators, Text gradient
  • Interactions: Clipboard detection, Form validation, Autofill & SMS
• Added interactive Playground for real-time customization of all options

Breaking Changes ⚠️ #

This is a complete rewrite with a new headless architecture. Migration required.

• New Headless Architecture: The package now provides both a headless core (PinInput) and a Material Design implementation (MaterialPinField)
• Unified Controller: PinInputController replaces separate TextEditingController, FocusNode, and errorAnimationController
• Theme System: New MaterialPinTheme with automatic ColorScheme resolution
• Renamed Parameters: See migration guide below

Features ✨ #

• Headless Core: Build completely custom PIN UIs with PinInput and PinCellData
• Material Design Ready: Use MaterialPinField for beautiful, ready-to-use PIN fields
• PinInputController: Single controller for text, focus, and error state management
  • setText(), clear(), text - Text control
  • triggerError(), clearError(), hasError - Error control
  • requestFocus(), unfocus(), hasFocus - Focus control
• Improved Animations: Scale, fade, slide, and none animation types
• All Cell Shapes: Outlined, filled, underlined, and circle
• Text Gradient: Apply gradients to PIN text via MaterialPinTheme.textGradient
• Custom Obscuring Widget: Use any widget for obscuring with obscuringWidget
• Form Integration: PinInputFormField for form validation
• SMS Autofill: Full autofill support with enableAutofill and autofillHints
• Haptic Feedback: Configurable haptic feedback types

Migration Guide #

Parameter Renames

Basic Migration

Before (v8.x):

PinCodeTextField(
  appContext: context,
  length: 6,
  controller: textController,
  focusNode: focusNode,
  pinTheme: PinTheme(
    shape: PinCodeFieldShape.box,
    activeColor: Colors.blue,
  ),
  onChanged: (value) {},
  onCompleted: (value) {},
)

After (v9.0):

final pinController = PinInputController();

MaterialPinField(
  length: 6,
  pinController: pinController,
  theme: MaterialPinTheme(
    shape: MaterialPinShape.outlined,
    focusedBorderColor: Colors.blue,
  ),
  onChanged: (value) {},
  onCompleted: (value) {},
)

Error Handling Migration

Before:

final errorController = StreamController<ErrorAnimationType>();
errorController.add(ErrorAnimationType.shake);

After:

final pinController = PinInputController();
pinController.triggerError();  // Triggers shake + sets error state
pinController.clearError();    // Clears error state

• Added activeBorderWidth, selectedBorderWidth, inactiveBorderWidth, disabledBorderWidth, errorBorderWidth

• Updated Dart SDK constraint sdk: ">=2.12.0 <4.0.0"
• Use PinCodePlatform instead Platform enum
• Numerous bug fixes, thanks to each and every contributor for resolving issues

• Added new attributes readOnly, textGradient, errorTextDirection, errorTextMargin, autoUnfocus
• Resolved blinkDebounce setState() after dispose() bug
• Example app refactor

• Fixed extra padding if autoValidate is not provided
• Added ScrollPadding, errorBorderColor

• Much requested feature placeholder has been added hintCharacter
• hintStyle has been added to customize the hint TextStyle

• Added useExternalAutoFillGroup to use this widget with external AutofillGroup
• Added fieldOuterPadding to add extra padding on each cells. Default to 0.0

• Added null-safety to the main branch

• Added haptic feedback
• Added animated obscure widget support obscuringWidget and blinkWhenObscuring

• Added Cursor support
• Added boxShadows
• Minimum Flutter version is set to 1.22.0

• Added iOS autofill with Flutter version 1.20.0
• Added onSave, onTap callbacks
• Added PastedTextStyle

• Added support for flutter-web

• Introduced PinTheme & DialogConfig
• Added beforeTextPaste callback
• Added onCompleted callback

• Added animations while changing value
• Added multiple customization parameters
• Pressing backspace focuses previous field