Class PinBox
A specialized input control for PIN codes, OTP verification, and security codes. Supports visual grouping, validation, masking, read-only display, and text normalization.
[TemplatePart("PART_ItemsPanel", typeof(Panel))]
[TemplatePart("PART_InputTextBox", typeof(TextBox))]
[PseudoClasses(new string[] { ":readonly" })]
public class PinBox : TemplatedControl, INotifyPropertyChanged, IDataContextProvider, ILogical, IThemeVariantHost, IResourceHost, IResourceNode, IStyleHost, ISetLogicalParent, ISetInheritanceParent, ISupportInitialize, INamed, IInputElement, IDataTemplateHost, ISetterValue
- Inheritance
-
AvaloniaObjectAnimatableStyledElementVisualLayoutableInteractiveInputElementControlTemplatedControlPinBox
- Implements
-
IDataContextProviderILogicalIThemeVariantHostIResourceHostIResourceNodeIStyleHostISetLogicalParentISetInheritanceParentINamedIInputElementIDataTemplateHostISetterValue
- Inherited Members
-
TemplatedControl.BackgroundPropertyTemplatedControl.BackgroundSizingPropertyTemplatedControl.BorderBrushPropertyTemplatedControl.BorderThicknessPropertyTemplatedControl.CornerRadiusPropertyTemplatedControl.FontFamilyPropertyTemplatedControl.FontFeaturesPropertyTemplatedControl.FontSizePropertyTemplatedControl.FontStylePropertyTemplatedControl.FontWeightPropertyTemplatedControl.FontStretchPropertyTemplatedControl.ForegroundPropertyTemplatedControl.LetterSpacingPropertyTemplatedControl.PaddingPropertyTemplatedControl.TemplatePropertyTemplatedControl.IsTemplateFocusTargetPropertyTemplatedControl.TemplateAppliedEventTemplatedControl.GetIsTemplateFocusTarget(Control)TemplatedControl.ApplyTemplate()TemplatedControl.GetTemplateFocusTarget()TemplatedControl.OnAttachedToLogicalTree(LogicalTreeAttachmentEventArgs)TemplatedControl.OnDetachedFromLogicalTree(LogicalTreeAttachmentEventArgs)TemplatedControl.OnTemplateChanged(AvaloniaPropertyChangedEventArgs)TemplatedControl.BackgroundTemplatedControl.BackgroundSizingTemplatedControl.BorderBrushTemplatedControl.BorderThicknessTemplatedControl.CornerRadiusTemplatedControl.FontFamilyTemplatedControl.FontFeaturesTemplatedControl.FontSizeTemplatedControl.FontStyleTemplatedControl.FontWeightTemplatedControl.FontStretchTemplatedControl.ForegroundTemplatedControl.LetterSpacingTemplatedControl.PaddingTemplatedControl.TemplateTemplatedControl.TemplateAppliedControl.FocusAdornerPropertyControl.TagPropertyControl.ContextMenuPropertyControl.ContextFlyoutPropertyControl.RequestBringIntoViewEventControl.LoadedEventControl.UnloadedEventControl.SizeChangedEventControl.OnLoaded(RoutedEventArgs)Control.OnUnloaded(RoutedEventArgs)Control.OnSizeChanged(SizeChangedEventArgs)Control.OnAttachedToVisualTreeCore(VisualTreeAttachmentEventArgs)Control.OnDetachedFromVisualTreeCore(VisualTreeAttachmentEventArgs)Control.OnPointerReleased(PointerReleasedEventArgs)Control.OnKeyUp(KeyEventArgs)Control.FocusAdornerControl.DataTemplatesControl.ContextMenuControl.ContextFlyoutControl.IsLoadedControl.TagControl.LoadedControl.UnloadedControl.SizeChangedInputElement.FocusablePropertyInputElement.IsEnabledPropertyInputElement.IsEffectivelyEnabledPropertyInputElement.CursorPropertyInputElement.IsKeyboardFocusWithinPropertyInputElement.IsFocusedPropertyInputElement.IsHitTestVisiblePropertyInputElement.IsPointerOverPropertyInputElement.IsTabStopPropertyInputElement.GotFocusEventInputElement.GettingFocusEventInputElement.LostFocusEventInputElement.LosingFocusEventInputElement.KeyDownEventInputElement.KeyUpEventInputElement.TabIndexPropertyInputElement.TextInputEventInputElement.TextInputMethodClientRequestedEventInputElement.PointerEnteredEventInputElement.PointerExitedEventInputElement.PointerMovedEventInputElement.PointerPressedEventInputElement.PointerReleasedEventInputElement.PointerCaptureLostEventInputElement.PointerWheelChangedEventInputElement.ContextRequestedEventInputElement.ContextCanceledEventInputElement.IsHoldingEnabledPropertyInputElement.IsHoldWithMouseEnabledPropertyInputElement.PinchEventInputElement.PinchEndedEventInputElement.PullGestureEventInputElement.PullGestureEndedEventInputElement.SwipeGestureEventInputElement.SwipeGestureEndedEventInputElement.ScrollGestureEventInputElement.ScrollGestureInertiaStartingEventInputElement.ScrollGestureEndedEventInputElement.PointerTouchPadGestureMagnifyEventInputElement.PointerTouchPadGestureRotateEventInputElement.PointerTouchPadGestureSwipeEventInputElement.TappedEventInputElement.RightTappedEventInputElement.HoldingEventInputElement.DoubleTappedEventInputElement.Focus(NavigationMethod, KeyModifiers)InputElement.OnAccessKey(RoutedEventArgs)InputElement.OnGettingFocus(FocusChangingEventArgs)InputElement.OnLosingFocus(FocusChangingEventArgs)InputElement.OnPointerEntered(PointerEventArgs)InputElement.OnPointerExited(PointerEventArgs)InputElement.OnPointerMoved(PointerEventArgs)InputElement.GetNextTabStopOverride()InputElement.GetPreviousTabStopOverride()InputElement.GetFirstFocusableElementOverride()InputElement.GetLastFocusableElementOverride()InputElement.OnPointerCaptureLost(PointerCaptureLostEventArgs)InputElement.OnPointerWheelChanged(PointerWheelEventArgs)InputElement.OnTapped(TappedEventArgs)InputElement.OnRightTapped(TappedEventArgs)InputElement.OnDoubleTapped(TappedEventArgs)InputElement.OnHolding(HoldingRoutedEventArgs)InputElement.UpdateIsEffectivelyEnabled()InputElement.GetIsHoldingEnabled(StyledElement)InputElement.GetIsHoldWithMouseEnabled(StyledElement)InputElement.FocusableInputElement.IsEnabledInputElement.CursorInputElement.IsKeyboardFocusWithinInputElement.IsFocusedInputElement.IsHitTestVisibleInputElement.IsPointerOverInputElement.IsTabStopInputElement.IsEffectivelyEnabledInputElement.TabIndexInputElement.KeyBindingsInputElement.IsEnabledCoreInputElement.GestureRecognizersInputElement.GotFocusInputElement.GettingFocusInputElement.LostFocusInputElement.LosingFocusInputElement.KeyDownInputElement.KeyUpInputElement.TextInputInputElement.TextInputMethodClientRequestedInputElement.PointerEnteredInputElement.PointerExitedInputElement.PointerMovedInputElement.PointerPressedInputElement.PointerReleasedInputElement.PointerCaptureLostInputElement.PointerWheelChangedInputElement.ContextRequestedInputElement.ContextCanceledInputElement.PinchInputElement.PinchEndedInputElement.PullGestureInputElement.PullGestureEndedInputElement.ScrollGestureInputElement.ScrollGestureInertiaStartingInputElement.ScrollGestureEndedInputElement.PointerTouchPadGestureMagnifyInputElement.PointerTouchPadGestureRotateInputElement.SwipeGestureInputElement.SwipeGestureEndedInputElement.PointerTouchPadGestureSwipeInputElement.TappedInputElement.RightTappedInputElement.HoldingInputElement.DoubleTappedInteractive.RaiseEvent(RoutedEventArgs)Interactive.BuildEventRoute(RoutedEvent)Layoutable.DesiredSizePropertyLayoutable.WidthPropertyLayoutable.HeightPropertyLayoutable.MinWidthPropertyLayoutable.MaxWidthPropertyLayoutable.MinHeightPropertyLayoutable.MaxHeightPropertyLayoutable.MarginPropertyLayoutable.HorizontalAlignmentPropertyLayoutable.VerticalAlignmentPropertyLayoutable.UseLayoutRoundingPropertyLayoutable.UpdateLayout()Layoutable.Measure(Size)Layoutable.Arrange(Rect)Layoutable.InvalidateMeasure()Layoutable.InvalidateArrange()Layoutable.AffectsMeasure<T>(params AvaloniaProperty[])Layoutable.AffectsArrange<T>(params AvaloniaProperty[])Layoutable.MeasureCore(Size)Layoutable.ArrangeCore(Rect)Layoutable.OnMeasureInvalidated()Layoutable.OnVisualParentChanged(Visual, Visual)Layoutable.WidthLayoutable.HeightLayoutable.MinWidthLayoutable.MaxWidthLayoutable.MinHeightLayoutable.MaxHeightLayoutable.MarginLayoutable.HorizontalAlignmentLayoutable.VerticalAlignmentLayoutable.DesiredSizeLayoutable.IsMeasureValidLayoutable.IsArrangeValidLayoutable.UseLayoutRoundingLayoutable.EffectiveViewportChangedLayoutable.LayoutUpdatedVisual.BoundsPropertyVisual.ClipToBoundsPropertyVisual.ClipPropertyVisual.IsVisiblePropertyVisual.OpacityPropertyVisual.OpacityMaskPropertyVisual.CacheModePropertyVisual.EffectPropertyVisual.HasMirrorTransformPropertyVisual.RenderTransformPropertyVisual.RenderTransformOriginPropertyVisual.FlowDirectionPropertyVisual.VisualParentPropertyVisual.ZIndexPropertyVisual.GetFlowDirection(Visual)Visual.SetFlowDirection(Visual, FlowDirection)Visual.InvalidateVisual()Visual.Render(DrawingContext)Visual.AffectsRender<T>(params AvaloniaProperty[])Visual.InvalidateMirrorTransform()Visual.BoundsVisual.ClipToBoundsVisual.ClipVisual.IsEffectivelyVisibleVisual.IsVisibleVisual.OpacityVisual.OpacityMaskVisual.CacheModeVisual.EffectVisual.HasMirrorTransformVisual.RenderTransformVisual.RenderTransformOriginVisual.FlowDirectionVisual.ZIndexVisual.VisualChildrenVisual.VisualRootVisual.BypassFlowDirectionPoliciesVisual.AttachedToVisualTreeVisual.DetachedFromVisualTreeStyledElement.DataContextPropertyStyledElement.NamePropertyStyledElement.ParentPropertyStyledElement.TemplatedParentPropertyStyledElement.ThemePropertyStyledElement.BeginInit()StyledElement.EndInit()StyledElement.ApplyStyling()StyledElement.InitializeIfNeeded()StyledElement.OnDataContextBeginUpdate()StyledElement.OnDataContextEndUpdate()StyledElement.OnInitialized()StyledElement.NameStyledElement.ClassesStyledElement.DataContextStyledElement.IsInitializedStyledElement.StylesStyledElement.StyleKeyStyledElement.ResourcesStyledElement.TemplatedParentStyledElement.ThemeStyledElement.LogicalChildrenStyledElement.PseudoClassesStyledElement.StyleKeyOverrideStyledElement.ParentStyledElement.ActualThemeVariantStyledElement.AttachedToLogicalTreeStyledElement.DetachedFromLogicalTreeStyledElement.DataContextChangedStyledElement.InitializedStyledElement.ResourcesChangedStyledElement.ActualThemeVariantChangedAnimatable.TransitionsPropertyAnimatable.OnPropertyChangedCore(AvaloniaPropertyChangedEventArgs)Animatable.TransitionsAvaloniaObject.CheckAccess()AvaloniaObject.VerifyAccess()AvaloniaObject.ClearValue(AvaloniaProperty)AvaloniaObject.ClearValue<T>(AvaloniaProperty<T>)AvaloniaObject.ClearValue<T>(StyledProperty<T>)AvaloniaObject.ClearValue<T>(DirectPropertyBase<T>)AvaloniaObject.GetHashCode()AvaloniaObject.GetValue(AvaloniaProperty)AvaloniaObject.GetValue<T>(StyledProperty<T>)AvaloniaObject.GetValue<T>(DirectPropertyBase<T>)AvaloniaObject.GetBaseValue<T>(StyledProperty<T>)AvaloniaObject.IsAnimating(AvaloniaProperty)AvaloniaObject.IsSet(AvaloniaProperty)AvaloniaObject.SetValue<T>(StyledProperty<T>, T, BindingPriority)AvaloniaObject.SetValue<T>(DirectPropertyBase<T>, T)AvaloniaObject.SetCurrentValue<T>(StyledProperty<T>, T)AvaloniaObject.Bind(AvaloniaProperty, BindingBase)AvaloniaObject.CoerceValue(AvaloniaProperty)AvaloniaObject.RaisePropertyChanged<T>(DirectPropertyBase<T>, T, T)AvaloniaObject.SetAndRaise<T>(DirectPropertyBase<T>, ref T, T)AvaloniaObject.InheritanceParentAvaloniaObject.this[AvaloniaProperty]AvaloniaObject.this[IndexerDescriptor]AvaloniaObject.DispatcherAvaloniaObject.PropertyChanged
Fields
AnimationDurationProperty
Defines the AnimationDuration property.
public static readonly StyledProperty<TimeSpan> AnimationDurationProperty
Field Value
- StyledProperty<TimeSpan>
CompletedCommandParameterProperty
Defines the CompletedCommandParameter property.
public static readonly StyledProperty<object?> CompletedCommandParameterProperty
Field Value
- StyledProperty<object>
CompletedCommandProperty
Defines the CompletedCommand property.
public static readonly StyledProperty<ICommand?> CompletedCommandProperty
Field Value
- StyledProperty<ICommand>
CursorBrushProperty
Defines the CursorBrush property.
public static readonly StyledProperty<IBrush?> CursorBrushProperty
Field Value
- StyledProperty<IBrush>
DefaultThemeProperty
Defines the DefaultTheme property.
public static readonly StyledProperty<PinBoxTheme?> DefaultThemeProperty
Field Value
- StyledProperty<PinBoxTheme>
DigitsOnlyProperty
Defines the DigitsOnly property.
public static readonly StyledProperty<bool> DigitsOnlyProperty
Field Value
- StyledProperty<bool>
ErrorTextProperty
Defines the ErrorText property.
public static readonly StyledProperty<string?> ErrorTextProperty
Field Value
- StyledProperty<string>
ErrorThemeProperty
Defines the ErrorTheme property.
public static readonly StyledProperty<PinBoxTheme?> ErrorThemeProperty
Field Value
- StyledProperty<PinBoxTheme>
FilledThemeProperty
Defines the FilledTheme property.
public static readonly StyledProperty<PinBoxTheme?> FilledThemeProperty
Field Value
- StyledProperty<PinBoxTheme>
FocusedThemeProperty
Defines the FocusedTheme property.
public static readonly StyledProperty<PinBoxTheme?> FocusedThemeProperty
Field Value
- StyledProperty<PinBoxTheme>
GroupLengthProperty
Defines the GroupLength property.
public static readonly StyledProperty<int> GroupLengthProperty
Field Value
- StyledProperty<int>
GroupLengthsProperty
Defines the GroupLengths property.
public static readonly StyledProperty<IReadOnlyList<int>?> GroupLengthsProperty
Field Value
- StyledProperty<IReadOnlyList<int>>
HasErrorProperty
Defines the HasError property.
public static readonly StyledProperty<bool> HasErrorProperty
Field Value
- StyledProperty<bool>
IsPasswordProperty
Defines the IsPassword property.
public static readonly StyledProperty<bool> IsPasswordProperty
Field Value
- StyledProperty<bool>
IsReadOnlyProperty
Defines the IsReadOnly property.
public static readonly StyledProperty<bool> IsReadOnlyProperty
Field Value
- StyledProperty<bool>
IsResponsiveProperty
Defines the IsResponsive property.
public static readonly StyledProperty<bool> IsResponsiveProperty
Field Value
- StyledProperty<bool>
LengthProperty
Defines the Length property.
public static readonly StyledProperty<int> LengthProperty
Field Value
- StyledProperty<int>
MinItemWidthProperty
Defines the MinItemWidth property.
public static readonly StyledProperty<double> MinItemWidthProperty
Field Value
- StyledProperty<double>
PasswordCharProperty
Defines the PasswordChar property.
public static readonly StyledProperty<char> PasswordCharProperty
Field Value
- StyledProperty<char>
SeparatorProperty
Defines the Separator property.
public static readonly StyledProperty<string?> SeparatorProperty
Field Value
- StyledProperty<string>
ShowCursorProperty
Defines the ShowCursor property.
public static readonly StyledProperty<bool> ShowCursorProperty
Field Value
- StyledProperty<bool>
SpacingProperty
Defines the Spacing property.
public static readonly StyledProperty<double> SpacingProperty
Field Value
- StyledProperty<double>
TextNormalizerProperty
Defines the TextNormalizer property.
public static readonly StyledProperty<Func<string, string>?> TextNormalizerProperty
Field Value
TextProperty
Defines the Text property.
public static readonly StyledProperty<string> TextProperty
Field Value
- StyledProperty<string>
ValidatorProperty
Defines the Validator property.
public static readonly StyledProperty<Func<string, string?>?> ValidatorProperty
Field Value
Properties
AnimationDuration
Gets or sets the duration of animations.
public TimeSpan AnimationDuration { get; set; }
Property Value
CompletedCommand
Gets or sets the command invoked when all PIN characters are entered.
public ICommand? CompletedCommand { get; set; }
Property Value
CompletedCommandParameter
Gets or sets the command parameter. When unset, the completed PIN text is used.
public object? CompletedCommandParameter { get; set; }
Property Value
CursorBrush
Gets or sets the cursor brush.
public IBrush? CursorBrush { get; set; }
Property Value
- IBrush
DefaultTheme
Gets or sets the default theme for empty boxes.
public PinBoxTheme? DefaultTheme { get; set; }
Property Value
DigitsOnly
Gets or sets whether only digit characters (0-9) are accepted. When false, letters and digits are allowed (useful for alphanumeric OTP codes).
public bool DigitsOnly { get; set; }
Property Value
ErrorText
Gets the current error text from validation.
public string? ErrorText { get; }
Property Value
ErrorTheme
Gets or sets the theme for boxes in error state.
public PinBoxTheme? ErrorTheme { get; set; }
Property Value
FilledTheme
Gets or sets the theme for filled boxes.
public PinBoxTheme? FilledTheme { get; set; }
Property Value
FocusedTheme
Gets or sets the theme for the focused box.
public PinBoxTheme? FocusedTheme { get; set; }
Property Value
GroupLength
Gets or sets the number of boxes in each visual group. Set to 0 to disable grouping.
public int GroupLength { get; set; }
Property Value
GroupLengths
Gets or sets explicit visual group sizes. When set, this takes precedence over GroupLength.
public IReadOnlyList<int>? GroupLengths { get; set; }
Property Value
HasError
Gets whether the PinBox has a validation error.
public bool HasError { get; }
Property Value
IsPassword
Gets or sets whether to obscure the input characters.
public bool IsPassword { get; set; }
Property Value
IsReadOnly
Gets or sets whether users can edit the PIN text.
public bool IsReadOnly { get; set; }
Property Value
IsResponsive
Gets or sets whether boxes shrink when the available width is smaller than the preferred width.
public bool IsResponsive { get; set; }
Property Value
Length
Gets or sets the number of PIN characters.
public int Length { get; set; }
Property Value
MinItemWidth
Gets or sets the smallest width a responsive PIN box can shrink to.
public double MinItemWidth { get; set; }
Property Value
PasswordChar
Gets or sets the character to display when in password mode.
public char PasswordChar { get; set; }
Property Value
Separator
Gets or sets the text displayed between visual groups.
public string? Separator { get; set; }
Property Value
ShowCursor
Gets or sets whether to show the blinking cursor.
public bool ShowCursor { get; set; }
Property Value
Spacing
Gets or sets the spacing between PIN boxes.
public double Spacing { get; set; }
Property Value
Text
Gets or sets the PIN text value.
public string Text { get; set; }
Property Value
TextNormalizer
Gets or sets a function used to normalize text before filtering and length clamping. This is useful for pasted SMS or email codes that include spaces, dashes, or mixed casing.
public Func<string, string>? TextNormalizer { get; set; }
Property Value
Validator
Gets or sets the validation function.
public Func<string, string?>? Validator { get; set; }
Property Value
Methods
ArrangeOverride(Size)
Positions child elements as part of a layout pass.
protected override Size ArrangeOverride(Size finalSize)
Parameters
finalSizeSizeThe size available to the control.
Returns
- Size
The actual size used.
Clear()
Clears all entered characters.
public void Clear()
MeasureOverride(Size)
Measures the control and its child elements as part of a layout pass.
protected override Size MeasureOverride(Size availableSize)
Parameters
availableSizeSizeThe size available to the control.
Returns
- Size
The desired size for the control.
OnApplyTemplate(TemplateAppliedEventArgs)
Called when the control's template is applied. In simple terms, this means the method is called just before the control is displayed.
protected override void OnApplyTemplate(TemplateAppliedEventArgs e)
Parameters
eTemplateAppliedEventArgsThe event args.
OnAttachedToVisualTree(VisualTreeAttachmentEventArgs)
Called when the control is added to a rooted visual tree.
protected override void OnAttachedToVisualTree(VisualTreeAttachmentEventArgs e)
Parameters
eVisualTreeAttachmentEventArgsThe event args.
OnCreateAutomationPeer()
Returns a new, type-specific Avalonia.Automation.Peers.AutomationPeer implementation for the control.
protected override AutomationPeer OnCreateAutomationPeer()
Returns
- AutomationPeer
The type-specific Avalonia.Automation.Peers.AutomationPeer implementation.
OnDetachedFromVisualTree(VisualTreeAttachmentEventArgs)
Called when the control is removed from a rooted visual tree.
protected override void OnDetachedFromVisualTree(VisualTreeAttachmentEventArgs e)
Parameters
eVisualTreeAttachmentEventArgsThe event args.
OnGotFocus(FocusChangedEventArgs)
Invoked when an unhandled Avalonia.Input.InputElement.GotFocusEvent reaches an element in its route that is derived from this class. Implement this method to add class handling for this event.
protected override void OnGotFocus(FocusChangedEventArgs e)
Parameters
eFocusChangedEventArgsData about the event.
OnKeyDown(KeyEventArgs)
Invoked when an unhandled Avalonia.Input.InputElement.KeyDownEvent reaches an element in its route that is derived from this class. Implement this method to add class handling for this event.
protected override void OnKeyDown(KeyEventArgs e)
Parameters
eKeyEventArgsData about the event.
OnLostFocus(FocusChangedEventArgs)
Invoked when an unhandled Avalonia.Input.InputElement.LostFocusEvent reaches an element in its route that is derived from this class. Implement this method to add class handling for this event.
protected override void OnLostFocus(FocusChangedEventArgs e)
Parameters
eFocusChangedEventArgsData about the event.
OnPointerPressed(PointerPressedEventArgs)
Invoked when an unhandled Avalonia.Input.InputElement.PointerPressedEvent reaches an element in its route that is derived from this class. Implement this method to add class handling for this event.
protected override void OnPointerPressed(PointerPressedEventArgs e)
Parameters
ePointerPressedEventArgsData about the event.
OnPropertyChanged(AvaloniaPropertyChangedEventArgs)
Called when a avalonia property changes on the object.
protected override void OnPropertyChanged(AvaloniaPropertyChangedEventArgs change)
Parameters
changeAvaloniaPropertyChangedEventArgsThe property change details.
OnTextInput(TextInputEventArgs)
Invoked when an unhandled Avalonia.Input.InputElement.TextInputEvent reaches an element in its route that is derived from this class. Implement this method to add class handling for this event.
protected override void OnTextInput(TextInputEventArgs e)
Parameters
eTextInputEventArgsData about the event.
ShakeAsync()
Plays a shake animation to indicate an error.
public Task ShakeAsync()
Returns
Events
Completed
Occurs when all PIN characters are entered.
public event EventHandler<PinBoxCompletedEventArgs>? Completed
Event Type
TextChanged
Occurs when the PIN text changes.
public event EventHandler<PinBoxTextChangedEventArgs>? TextChanged