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
Six Digits
With Error
Locked
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
| Variant | What it is |
|---|---|
| empty | Hollow dots. |
| partial | Filled dots for entered digits. |
| error | Red dots and message. |
| biometric | Face ID key in the bottom left. |
| locked | Keys 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
| Prop | Type | Default | Description |
|---|---|---|---|
length | number | 4 | Number of digits, 4 to 6 |
value | string | undefined (uncontrolled) | Controlled digits entered |
defaultValue | string | "" | Initial digits (uncontrolled) |
onChange | (pin: string) => void | none | Called with the digits after every key |
label | string | none | Label above the dots ("Enter your PIN") |
error | string | none | Error message, role alert; the dots turn red |
biometric | boolean | false | Shows the Face ID key |
biometricLabel | string | 'Face ID' | Text of the biometric key |
locked | boolean | false | Locks the keypad after too many tries |
lockedText | string | 'Too many tries. Sign in with your password.' | Text under a locked keypad |
onComplete | (pin: string) => void | none | Called with the PIN when the last digit is entered |
onBiometric | () => void | none | Called 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>
| Kind | Name | Description |
|---|---|---|
| attribute | length | Number of digits, 4 to 6; default 4 |
| attribute | value | Controlled digits entered; default undefined (uncontrolled) |
| attribute | default-value / defaultValue | Initial digits (uncontrolled); default "" |
| attribute | label | Label above the dots ("Enter your PIN"); default none |
| attribute | error | Error message, role alert; the dots turn red; default none |
| attribute | biometric | Shows the Face ID key; default false |
| attribute | biometric-label / biometricLabel | Text of the biometric key; default 'Face ID' |
| attribute | locked | Locks the keypad after too many tries; default false |
| attribute | locked-text / lockedText | Text under a locked keypad; default 'Too many tries. Sign in with your password.' |
| attribute | default-checked / defaultChecked | |
| attribute | auto-focus / autoFocus | |
| event | co-change | Called with the digits after every key; default none (React: onChange) |
| event | co-complete | Called with the PIN when the last digit is entered; default none (React: onComplete) |
| event | co-biometric | Called when the biometric key is pressed; default none (React: onBiometric) |