Allows users to input a sequence of one-character alphanumeric inputs.
The Input PIN component is a web component built from scratch to allow users to input a sequence of one-character alphanumeric inputs. This is particularly useful in scenarios such as:
To get started, simply use the <uk-input-pin> markup in your HTML code.
There are several ways to capture values from the <uk-input-pin> component. The simplest approach is to add a name attribute to the component. When you do this, a hidden input field with the specified name will be automatically generated, allowing you to easily capture the selected value on your server.
By default, the Input PIN component is set to accept 6 characters. However, you can easily customize this by adding the length attribute to the <uk-input-pin> element. Simply specify the desired length as a numerical value, and the component will automatically adjust to accommodate the specified number of inputs.
By default, the input fields in the Input PIN component are displayed adjacent to each other. To add visual separation between each input, simply add the .uk-input-pin-separated class to the cls attribute. This will add gaps between each input, making it easier for users to distinguish between individual characters.
There are several size modifiers available. Just add one of the following classes to the cls attribute to make the input smaller or larger.
| Class | Description |
|---|---|
.uk-form-xsmall | Applies extra small size. |
.uk-form-small | Applies small size. |
.uk-form-medium | Applies medium size. |
.uk-form-large | Applies large size. |
To prevent user input, add the disabled attribute to the <uk-input-pin> element. This will disable all input fields, making it impossible for users to enter or modify the PIN sequence.
To indicate an error state in the form, simply add the .uk-form-danger class to the cls attribute. This will apply a “danger” state to the component, providing visual feedback to the user.
The Input PIN component supports internationalization through multiple methods with the following priority order (highest to lowest):
i18n attribute or script tag)<script id="uk-i18n">)Place this in your document <head> or before any input-pin components:
| Key | Default | Description |
|---|---|---|
label | PIN Code | Main label for the PIN input group |
description | Enter {length}-digit code | Description text (supports {length} placeholder) |
field-label | Digit {n} of {total} | ARIA label for individual fields (supports {n}, {total} placeholders) |
loaded | PIN input ready | Screen reader announcement when component loads |
complete | PIN entry complete | Screen reader announcement when all fields are filled |
field-filled | Field {n} filled | Screen reader announcement when a field is filled (supports {n} placeholder) |
invalid-character | Invalid character entered | Screen reader announcement for invalid input |
The Input PIN component supports custom CSS classes through the cls attribute. This allows you to style specific elements within the PIN input without modifying the component’s internal structure.
Apply a class to the default element (host-inner):
Target specific elements within the input pin:
| Target | Description |
|---|---|
host-inner | The main container div |
wrapper | The div wrapping all input fields |
input | Individual input fields |
label | The label element (visually hidden by default) |
description | The description element (visually hidden by default) |
The Input PIN component supports custom inline styles through the stl attribute. This allows you to apply specific CSS styles to individual elements within the PIN input.
Apply styles to the default element (host-inner):
Target specific elements with custom styles:
The stl attribute supports the same targets as the cls attribute. See the Available cls targets table above for a complete list of targetable elements.
The Input PIN component provides comprehensive keyboard support:
| Key | Action |
|---|---|
| Type character | Auto-advances to next field |
| Backspace | Deletes character and moves to previous field (if empty) |
| Delete | Moves to next field (if current is empty) |
| Arrow Left | Move to previous field |
| Arrow Right | Move to next field |
| Home | Jump to first field |
| End | Jump to last filled field |
| Paste (Ctrl+V) | Distributes pasted content across fields |
The component supports pasting complete PIN codes. When a user pastes text:
When loading Web Components, there may be a brief delay before the content is fully rendered. This can result in a flash of unstyled content or unprocessed templates. To mitigate this issue, consider setting a predefined height on the parent element to prevent layout shift and ensure a smooth user experience.
The following attributes are available for this component:
| Name | Type | Default | Description |
|---|---|---|---|
autofocus | Boolean | false | Automatically focuses on the first input field when the component is rendered |
length | Number | 6 | Number of PIN digits/characters to collect |
input-mode | String | numeric | Input mode for mobile keyboards: numeric or text |
pattern | String | Pattern for input validation (e.g., [0-9] for digits only) | |
show-labels | Boolean | false | Whether to show labels and descriptions visually (default: hidden but accessible) |
name | String | Name attribute for the hidden input field, enabling form submission | |
disabled | Boolean | false | Disables all input fields, making the entire component read-only |
required | Boolean | false | Marks the PIN input as required for form validation |
value | String | Pre-populated PIN value (validated against pattern if provided) | |
cls | String | Custom CSS classes. Can be simple string or JSON object for targeting elements | |
stl | String | Custom inline styles. Can be simple string or JSON object for targeting elements | |
i18n | String | Internationalization strings as JSON object or via configuration script | |
force-prevent-rerender | Boolean | false | Prevents component rerendering (useful for HTMX or SPA scenarios) |
The Input PIN component triggers the following events:
| Name | Description |
|---|---|
uk-input-pin:change | Fired when the PIN value changes. Event detail contains {value: string}. |
uk-input-pin:complete | Fired when all PIN fields are filled. Event detail contains {value: string}. |