Skip to main content

PinEntry

BasicInputs<co-pin-entry>

PinEntry is a 4 to 6 digit keypad with dots, for mobile sign-in and quick re-authentication.

import { PinEntry } from 'health-components';

Examples​

Showcase​

Storybook

Six Digits​

Storybook

With Error​

Storybook

Locked​

Storybook

Usage​

<PinEntry length={4} label="Enter your PIN" biometric onComplete={unlock} error={pinError} />

When to use​

  • Unlocking the mobile EHR, confirming an e-prescription for controlled substances (with the second factor).

When not to use​

  • First sign-in: use username and password with 2FA.

Variants and states​

VariantWhat it is
emptyHollow dots.
partialFilled dots for entered digits.
errorRed dots and message.
biometricFace ID key in the bottom left.
lockedKeys disabled after too many tries.

Accessibility​

  • Dots have role status with "N of 4 digits entered".
  • The delete key is named "Delete last digit".
  • Keys are 56px tall, above the 44px touch minimum.

Do and don't​

  • Do: Offer Face ID next to the PIN.
  • Don't: Show the digits.

Props​

PropTypeDefaultDescription
lengthnumber4Number of digits, 4 to 6
valuestringundefined (uncontrolled)Controlled digits entered
defaultValuestring""Initial digits (uncontrolled)
onChange(pin: string) => voidnoneCalled with the digits after every key
labelstringnoneLabel above the dots ("Enter your PIN")
errorstringnoneError message, role alert; the dots turn red
biometricbooleanfalseShows the Face ID key
biometricLabelstring'Face ID'Text of the biometric key
lockedbooleanfalseLocks the keypad after too many tries
lockedTextstring'Too many tries. Sign in with your password.'Text under a locked keypad
onComplete(pin: string) => voidnoneCalled with the PIN when the last digit is entered
onBiometric() => voidnoneCalled when the biometric key is pressed

Also accepts native attributes, including defaultChecked, autoFocus, plus className and event handlers on the root element.

Angular, Vue and HTML​

Register the elements once (Angular guide), then use <co-pin-entry>. Attributes take strings; arrays and objects are set as properties (Angular [prop], Vue :prop) or as JSON attributes. Callbacks are DOM events with the value in event.detail.

Angular template
<co-pin-entry length="…" value="…" (co-change)="onChange($event.detail)"></co-pin-entry>
KindNameDescription
attributelengthNumber of digits, 4 to 6; default 4
attributevalueControlled digits entered; default undefined (uncontrolled)
attributedefault-value / defaultValueInitial digits (uncontrolled); default ""
attributelabelLabel above the dots ("Enter your PIN"); default none
attributeerrorError message, role alert; the dots turn red; default none
attributebiometricShows the Face ID key; default false
attributebiometric-label / biometricLabelText of the biometric key; default 'Face ID'
attributelockedLocks the keypad after too many tries; default false
attributelocked-text / lockedTextText under a locked keypad; default 'Too many tries. Sign in with your password.'
attributedefault-checked / defaultChecked
attributeauto-focus / autoFocus
eventco-changeCalled with the digits after every key; default none (React: onChange)
eventco-completeCalled with the PIN when the last digit is entered; default none (React: onComplete)
eventco-biometricCalled when the biometric key is pressed; default none (React: onBiometric)