Skip to content
Kimenpre-v1documentation home
Color scheme

ki-code-input

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.

Theme for this example
Color scheme for this example
<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.

Theme for this example
Color scheme for this example
<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

AttributePropertyTypeDefaultDescription
disableddisabledbooleanfalseDisable editing, sequential focus and form participation.
error-texterrorTextstring | undefined–Message for a failing code constraint. Omit to use the browser's message.
help-texthelpTextstring | undefined–Instructions saying where the code was sent and how long it is valid.
labellabelstring–Visible accessible name. Supply a label in the language of the form.
lengthlengthnumber6Number of cells and maximum code length. Unsupported lengths fall back to six.
namenamestring | undefined–Key for the single value submitted to the enclosing form.
requiredrequiredbooleanfalseRequire a complete code before submitting. An optional field may be empty.
sizesize"md" | "sm"'md'Medium or small cells. The form region's density adjusts both sizes.
typetype"alphanumeric" | "numeric"'numeric'Allowed characters and keyboard hint. Alphanumeric mode preserves ASCII letter case.
valuevaluestring''The current code, including leading zeros. Use the attribute to declare the reset value. Programmatic assignments are normalized and silent.

Events

EventDetail typeDescription
ki-completeCustomEvent<KiCodeInputDetail>Emitted after the input event when the edited code fills all the cells.
ki-inputCustomEvent<KiCodeInputDetail>Emitted when a user edit changes the code.

CSS parts

PartDescription
cellDecorative box for one code character.
errorPolite validation message that replaces the instructions.
fieldEnclosure of the native input and its visual boxes.
helpDelivery and validity instructions read with the field.
inputSingle native text input, responsible for editing and autofill.
labelVisible 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.

TokenDescription
--ki-code-input-active-borderFocus outline around the active or selected cells.
--ki-code-input-backdrop-filterOptional compositing filter behind a code cell.
--ki-code-input-bgResting code cell fill.
--ki-code-input-bg-imageOptional image painted over the code cell fill.
--ki-code-input-blink-durationDuration of one code caret blink.
--ki-code-input-borderResting code cell boundary.
--ki-code-input-cell-sizeDefault code cell edge before applying control density.
--ki-code-input-cell-size-smSmall code cell edge before applying control density.
--ki-code-input-disabled-fgCode character ink while the field is disabled.
--ki-code-input-error-borderCode cell boundary after failed validation.
--ki-code-input-fgResting code character ink.
--ki-code-input-font-sizeCode character size.
--ki-code-input-gapInline space between code cells.
--ki-code-input-radiusCode cell corner radius.
--ki-code-input-selection-bgBackground of a selected code character.
--ki-code-input-selection-fgInk of a selected code character.
--ki-code-input-touch-font-sizeMinimum native input text size on a coarse pointer.
--ki-control-border-widthStroke width of the boundary of a compact control.
--ki-density-control-offsetAdded 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-minThe 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-widthThickness 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-xsThe xs spacing step for a stack or grid gap.
--ki-text-danger-high-emsemantic color for text danger high em.
--ki-text-high-emsemantic color for text high em.
--ki-text-supportingSupporting 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-bodysemantic font family for typography family body.
--ki-typography-family-monosemantic font family for typography family mono.
--ki-typography-line-height-body-1semantic dimension for typography line height body 1.
--ki-typography-line-height-caption-2semantic dimension for typography line height caption 2.
--ki-typography-size-body-1semantic dimension for typography size body 1.
--ki-typography-size-caption-2semantic dimension for typography size caption 2.
--ki-typography-weight-body-mediumsemantic font weight for typography weight body medium.
--ki-typography-weight-body-normalsemantic font weight for typography weight body normal.
--ki-typography-weight-body-semiboldsemantic font weight for typography weight body semibold.

Workshop

Open ki-code-input in Storybook