ki-code-input
@kimen/elements/ki-code-input- Source
- Agent reference
Use ki-code-input for four to eight digits or ASCII letters and digits. Use
ki-input for passwords, longer codes or free text. The code is one native
text field, so a person can paste the entire code, edit it with the keyboard
or use the browser’s one-time-code suggestion when available.
<ki-code-input label="Verification code" name="otp" required help-text="We sent a code to [email protected]. It is valid for ten minutes."></ki-code-input>Alphanumeric codes
Set type="alphanumeric" when the code includes letters. Specify the length and
tell the person which message contains the code.
<ki-code-input label="Recovery code" length="4" type="alphanumeric" size="sm" help-text="Enter the four characters from your verification email."></ki-code-input>Verification and resend
Give the field a visible label. Include the delivery destination and validity
period in the help text. Place a ki-button variant="ghost" type="button" next
to the field for resending a code. The application tracks expiration and
handles resend. Let the person know when the code expires and when a new
code is issued.
Use error-text to customize a constraint message. For a code rejected by
the server, set the error with setCustomValidity(message) and call
reportValidity() on the custom-elements build. Clear the error with
setCustomValidity('') when the person edits or requests a new code.
Listen for ki-input to follow edits and ki-complete to know when all boxes
are filled. Only submit on completion if the person cannot lose work. A
named field submits one string, including leading zeroes.
API reference
When to use: Collect a one-time code of four to eight characters for sign-in or verification.
When not to use: Use ki-input for passwords, long codes or free text.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
disabled | disabled | boolean | false | Disable editing, sequential focus and form participation. |
error-text | errorText | string | undefined | – | Message for a failing code constraint. Omit to use the browser's message. |
help-text | helpText | string | undefined | – | Instructions saying where the code was sent and how long it is valid. |
label | label | string | – | Visible accessible name. Supply a label in the language of the form. |
length | length | number | 6 | Number of cells and maximum code length. Unsupported lengths fall back to six. |
name | name | string | undefined | – | Key for the single value submitted to the enclosing form. |
required | required | boolean | false | Require a complete code before submitting. An optional field may be empty. |
size | size | "md" | "sm" | 'md' | Medium or small cells. The form region's density adjusts both sizes. |
type | type | "alphanumeric" | "numeric" | 'numeric' | Allowed characters and keyboard hint. Alphanumeric mode preserves ASCII letter case. |
value | value | string | '' | The current code, including leading zeros. Use the attribute to declare the reset value. Programmatic assignments are normalized and silent. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-complete | CustomEvent<KiCodeInputDetail> | Emitted after the input event when the edited code fills all the cells. |
ki-input | CustomEvent<KiCodeInputDetail> | Emitted when a user edit changes the code. |
CSS parts
| Part | Description |
|---|---|
cell | Decorative box for one code character. |
error | Polite validation message that replaces the instructions. |
field | Enclosure of the native input and its visual boxes. |
help | Delivery and validity instructions read with the field. |
input | Single native text input, responsible for editing and autofill. |
label | Visible label supplying the native input's accessible name. |
CSS custom properties
The public styling contract of ki-code-input: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-code-input-active-border | Focus outline around the active or selected cells. |
--ki-code-input-backdrop-filter | Optional compositing filter behind a code cell. |
--ki-code-input-bg | Resting code cell fill. |
--ki-code-input-bg-image | Optional image painted over the code cell fill. |
--ki-code-input-blink-duration | Duration of one code caret blink. |
--ki-code-input-border | Resting code cell boundary. |
--ki-code-input-cell-size | Default code cell edge before applying control density. |
--ki-code-input-cell-size-sm | Small code cell edge before applying control density. |
--ki-code-input-disabled-fg | Code character ink while the field is disabled. |
--ki-code-input-error-border | Code cell boundary after failed validation. |
--ki-code-input-fg | Resting code character ink. |
--ki-code-input-font-size | Code character size. |
--ki-code-input-gap | Inline space between code cells. |
--ki-code-input-radius | Code cell corner radius. |
--ki-code-input-selection-bg | Background of a selected code character. |
--ki-code-input-selection-fg | Ink of a selected code character. |
--ki-code-input-touch-font-size | Minimum native input text size on a coarse pointer. |
--ki-control-border-width | Stroke width of the boundary of a compact control. |
--ki-density-control-offset | Added to the block size of every scaled control and row (button, icon button, field, select, textarea, option, list item, tab). Components floor the result at ki.size.target-min. |
--ki-density-target-min | The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). |
--ki-focus-ring-width | Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once. |
--ki-layout-spacing-xs | The xs spacing step for a stack or grid gap. |
--ki-text-danger-high-em | semantic color for text danger high em. |
--ki-text-high-em | semantic color for text high em. |
--ki-text-supporting | Supporting text of an enabled control: field labels, placeholders, list secondary lines, quiet button labels and unselected tabs. A role, distinct from the med-em emphasis step it resolves to, so a mode can strengthen enabled supporting text without touching the disabled ink that also draws from med-em (directly, or through text.muted). |
--ki-typography-family-body | semantic font family for typography family body. |
--ki-typography-family-mono | semantic font family for typography family mono. |
--ki-typography-line-height-body-1 | semantic dimension for typography line height body 1. |
--ki-typography-line-height-caption-2 | semantic dimension for typography line height caption 2. |
--ki-typography-size-body-1 | semantic dimension for typography size body 1. |
--ki-typography-size-caption-2 | semantic dimension for typography size caption 2. |
--ki-typography-weight-body-medium | semantic font weight for typography weight body medium. |
--ki-typography-weight-body-normal | semantic font weight for typography weight body normal. |
--ki-typography-weight-body-semibold | semantic font weight for typography weight body semibold. |