ki-input
@kimen/elements/ki-input- Source
- Agent reference
A token-styled single-line text field with native input semantics. Always
provide a visible label; choose the type and autocomplete that match
the entry purpose.
<ki-input label="Work email" name="email" type="email" required></ki-input>Examples
Section titled “Examples”In a form
Section titled “In a form”label is mandatory — it is the accessible name. The field participates in
native form submission:
<form onsubmit="event.preventDefault()"><ki-input label="Work email" name="email" type="email" required></ki-input><ki-button variant="primary">Subscribe</ki-button></form>Read-only and disabled are distinct
Section titled “Read-only and disabled are distinct”Read-only stays focusable and is submitted; disabled is neither:
<ki-input label="Plan" value="Pro" readonly></ki-input><ki-input label="Legacy ID" value="A-1042" disabled></ki-input>start and end hold decorations; they follow the writing direction in
RTL:
<ki-input label="Search components" type="search" placeholder="ki-button"><span slot="start" aria-hidden="true">🔍</span></ki-input>Submit action inside the field
Section titled “Submit action inside the field”Use action for a one-field form with a single submit button. The button sits
after the end adornment and has its own tab stop. Pressing Enter in the
entry also submits the form.
<form role="search" onsubmit="event.preventDefault()"><ki-input type="search" name="q" label="Search docs" placeholder="Components, tokens…"> <ki-button slot="action" size="sm" variant="secondary" type="submit">Search</ki-button></ki-input></form>For an icon-only action, give ki-icon-button size="sm" a label and call
form.requestSubmit() from its click handler. Place form-wide or unrelated
actions beside the field. Use end for clear or reveal controls.
Appearance and character limits
Section titled “Appearance and character limits”Set appearance to outlined for a full border or filled for a
tinted surface with a bottom indicator. Both keep the label above the field.
The default appearance follows the theme.
Set minlength and maxlength to use the native input limits. With
a maximum, show-count adds the current length to the field description
and announces when the user reaches the limit.
<ki-input label="Workspace name" appearance="outlined" minlength="3" maxlength="30" show-count help-text="Shown to members" value="Kimen design"></ki-input><ki-input label="Price" appearance="filled" value="49.00"><span slot="start">EUR</span><span slot="end">/ month</span></ki-input>API reference
Section titled “API reference”When to use: collect one line of free text from a person, always with a visible label; choose the type and autocomplete that match the entry purpose.
When not to use: multiline text, predefined choices, boolean state, numeric stepper entry, or placeholder-only labeling.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
ai-suggestion-text | aiSuggestionText | string | 'Suggested by AI' | Localized provenance description read alongside help or an error when the end slot contains an AI label. Use this to translate the description. |
appearance | appearance | "default" | "filled" | "outlined" | undefined | 'default' | Field appearance. default uses the current theme, outlined draws a full border, and filled uses a tinted surface and bottom indicator. The visible label stays above the field. When to use: set an explicit appearance when fields must share a shape across themes. |
autocomplete | autocomplete | string | undefined | – | Native autocomplete detail token forwarded to the internal input. When NOT to use: omit when no autofill entry purpose is known. |
disabled | disabled | boolean | false | Prevents editing, removes the field from keyboard reach and exposes the unavailable state through the internal native input. When NOT to use: do not use disabled for readonly reference values. |
error-text | errorText | string | undefined | – | Message shown in place of the help text once the person's answer fails a constraint (required, type or a length limit), and the field's validationMessage. Say how to fix the answer ("Enter an email address like [email protected]"). Without it the browser's own message shows, in the browser's language. An error set with setCustomValidity outranks it. When NOT to use: do not use it for server-side or cross-field errors; call setCustomValidity for those. |
help-text | helpText | string | undefined | – | One line of help under the field, read with it as its description: the format expected, or why the answer is asked. While an error shows, the error takes its place. When NOT to use: do not repeat the label, and do not use it for error messages; use error-text. |
label | label | string | – | Visible label rendered next to the entry area and used as the accessible name. This is mandatory for valid usage. When NOT to use: never use placeholder as a label substitute. |
label-hint | labelHint | string | undefined | – | Short text shown after the label and read with it as part of the field's name, so people know before submitting whether to answer: "(optional)" on the few optional fields of a mostly required form, or "(required)" the other way round, in the page's own language. It changes no validation; set required for that, and keep the two consistent. When NOT to use: do not put instructions or formats in it (use help-text), errors (use error-text), or a repeat of the label. |
maxlength | maxlength | number | undefined | – | Native maximum length in UTF-16 code units. The input prevents user entry past this limit. When to use: cap the number of characters people can enter. |
minlength | minlength | number | undefined | – | Native minimum length in UTF-16 code units for a nonempty user edit. When to use: require a minimum number of characters in an answer. |
name | name | string | undefined | – | Form-data key for the submitted value. When NOT to use: omit when the field must not contribute named form data. |
placeholder | placeholder | string | undefined | – | Hint shown when the field is empty. When NOT to use: do not use placeholder as the accessible name. |
readonly | readonly | boolean | false | Makes the value focusable and selectable while rejecting edits. When NOT to use: use disabled when the value must be unavailable and excluded from forms. |
required | required | boolean | false | Marks the field as required for native constraint validation. When NOT to use: do not use required on optional fields. |
show-count | showCount | boolean | undefined | false | Shows the current count and maximum next to the help or error text and announces reaching or exceeding the limit. Requires maxlength. When to use: give people feedback while writing to a limit. |
size | size | "lg" | "md" | "sm" | "xl" | "xs" | 'md' | Token-backed field size (--ki-input-{size}-* tokens): the field box is 24, 32, 40, 48 or 56px tall in onmars, with its padding, radius, text and icon box; the label and help text follow in three steps. An unrecognized value matches no style rule and keeps the medium metrics. When to use: match the size of the buttons and fields around it. When NOT to use: do not pick a smaller size to fit a dense region or a larger one for touch; declare data-ki-density on the region instead, which composes with every size. |
type | type | "email" | "password" | "search" | "tel" | "text" | "url" | 'text' | Entry kind with native single-line input semantics. Unknown runtime values fall back to text; number is not a v1 input kind. When NOT to use: use future numeric controls for locale-aware number entry. |
value | value | string | '' | Live text value. The attribute declares the initial default; the property is the current value and programmatic assignments are silent. Deviation from native (deliberate, research D2): assigning the ATTRIBUTE programmatically also replaces the displayed value, silently — native inputs would keep the user's dirty value. Form reset restores the attribute's current value. When NOT to use: do not observe user edits by polling; listen for input and change (both re-dispatched composed across the shadow boundary). |
Events
| Event | Detail type | Description |
|---|---|---|
change | Event | Fired when the user commits an edited value (native text-field timing, such as on blur), composed across the shadow boundary; value is already current when listeners run. When to use: react to a committed value. When NOT to use: do not use it for per-keystroke updates; the native input event carries those. |
Slots
| Slot | Description |
|---|---|
action | One small submit action inside the field after the end adornment. Use for one-field forms such as search or subscribe. Place a named ki-button size="sm" type="submit" here, or wire a labeled ki-icon-button size="sm" to request form submission. The action has its own tab stop. Use the end slot for clear or reveal controls. |
end | Trailing icon or text affix inside the field. Follows writing direction. A directly slotted AI label also describes the field as suggested by AI. |
start | Leading icon or text affix inside the field. Follows writing direction. |
CSS parts
| Part | Description |
|---|---|
count | Current character count and maximum at the end of the field message row. |
error | Error line shown in place of the help text while the field is invalid after the person answered or submitted; a polite live region, starting with a decorative error symbol. |
field | Enclosure wrapper for background, border, radius and focus ring. |
help | Help line under the field, read as the field's description. |
input | Internal native input that owns entry text, caret and selection. |
label | Visible label that provides the accessible name. |
label-hint | The label-hint text after the label text, inside the label and part of the accessible name; rendered only while a hint is set. |
CSS custom properties
The public styling contract of ki-input: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--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-input-action-gap | Gap between the input action and the preceding control or adornment. |
--ki-input-action-padding-end | Inline-end inset between the input action and the inside edge of the field border. |
--ki-input-appearance-border-width | Resting stroke width of both explicit text field appearances. |
--ki-input-border-block-end-width | dimension used by the input component for border block end width. |
--ki-input-border-block-start-width | dimension used by the input component for border block start width. |
--ki-input-border-inline-end-width | dimension used by the input component for border inline end width. |
--ki-input-border-inline-start-width | dimension used by the input component for border inline start width. |
--ki-input-count-bg | Resting character count surface over the surrounding page. |
--ki-input-count-fg | Character count when the value fits the maximum. |
--ki-input-count-over-bg | Over-limit character count surface over the surrounding page. |
--ki-input-count-over-fg | Character count when the value exceeds the maximum. |
--ki-input-disabled-bg | color used by the input component for disabled background. |
--ki-input-disabled-border | color used by the input component for disabled border. |
--ki-input-disabled-fg | color used by the input component for disabled foreground (MarsUI disabled text Text/base_em; disabled cells are exempt from the contrast sweep). |
--ki-input-disabled-label-fg | color used by the input component for disabled label foreground. |
--ki-input-disabled-placeholder-fg | color used by the input component for disabled placeholder foreground. |
--ki-input-filled-backdrop-filter | Optional backdrop filter of a filled field. |
--ki-input-filled-bg | Surface of a filled text field. |
--ki-input-filled-bg-image | Optional background image of a filled field. |
--ki-input-filled-fg | Entered text on a filled field. |
--ki-input-filled-focus-width | Stroke width of the block-end indicator while focused. |
--ki-input-filled-indicator | Continuous block-end edge of an enabled filled text field. |
--ki-input-filled-placeholder-fg | Placeholder on a filled field. |
--ki-input-filled-radius | Block-start corner radius of a filled text field. |
--ki-input-focus-bg | color used by the input component for focus background (MarsUI active state switches the fill to Surface/Special white / dark s2 — modeled with the scheme ladder s0). |
--ki-input-focus-fg | color used by the input component for focus foreground. |
--ki-input-focus-label-fg | color used by the input component for focus label foreground (MarsUI label is Text/med_em in every non-disabled state — active and danger included; the danger signal lives in the hint). |
--ki-input-focus-placeholder-fg | color used by the input component for focus placeholder foreground (Text/med_em — a declared a11y deviation from the MarsUI placeholder binding Text/low_em, which reads 2.66-3.13:1 on the light field fills; a placeholder is not the accessible name but it is still text, so the contrast gate holds it to 4.5:1). |
--ki-input-focus-ring-color | color used by the input component for focus ring color. |
--ki-input-focus-ring-offset | dimension used by the input component for focus ring offset. |
--ki-input-focus-ring-shadow | shadow used by the input component for the focus ring glow (MarsUI Focus/primary: 3px spread ring at 20% — see ki.focus.primary. specs/002-ki-button/design-extraction.md §2.5 recorded 40%, having read the alpha off the Dark canvas mode, same double mechanism as ki-button: glow plus the opaque indicator). |
--ki-input-focus-ring-width | dimension used by the input component for focus ring width. |
--ki-input-font-size | dimension used by the input component for font size. |
--ki-input-font-size-touch | dimension used by the input component for the text a person types under a coarse primary pointer: 16px, under which Safari on iOS zooms the page into the focused field (spec 048). The onmars type scale has no 16px step. |
--ki-input-font-weight | font weight used by the input component for font weight. |
--ki-input-gap | dimension used by the input component for gap. |
--ki-input-height | dimension used by the input component for height (MarsUI Input_field md cell: min-height 40px; consume as min-block-size so the field can grow). |
--ki-input-hover-bg | color used by the input component for hover background (MarsUI hover = s2 + Black/3 overlay; s3 is the nearest token). |
--ki-input-hover-border | color used by the input component for hover border. |
--ki-input-hover-fg | color used by the input component for hover foreground. |
--ki-input-hover-label-fg | color used by the input component for hover label foreground (MarsUI label is Text/med_em in every non-disabled state — active and danger included; the danger signal lives in the hint). |
--ki-input-hover-placeholder-fg | color used by the input component for hover placeholder foreground (Text/med_em — a declared a11y deviation from the MarsUI placeholder binding Text/low_em, which reads 2.66-3.13:1 on the light field fills; a placeholder is not the accessible name but it is still text, so the contrast gate holds it to 4.5:1). |
--ki-input-icon-size | dimension used by the input component for icon size. |
--ki-input-invalid-bg | color used by the input component for invalid background (MarsUI danger state keeps the white active fill; the ring and hint carry the signal). |
--ki-input-invalid-border | color used by the input component for invalid border. |
--ki-input-invalid-fg | color used by the input component for invalid foreground. |
--ki-input-invalid-label-fg | color used by the input component for invalid label foreground (MarsUI label is Text/med_em in every non-disabled state — active and danger included; the danger signal lives in the hint). |
--ki-input-invalid-placeholder-fg | color used by the input component for invalid placeholder foreground (Text/med_em — a declared a11y deviation from the MarsUI placeholder binding Text/low_em, which reads 2.66-3.13:1 on the light field fills; a placeholder is not the accessible name but it is still text, so the contrast gate holds it to 4.5:1). |
--ki-input-invalid-ring | shadow used by the input component for the persistent invalid ring (MarsUI Focus/danger: 3px danger-500 alpha spread; applied as box-shadow while :state(user-invalid)). |
--ki-input-label-font-size | dimension used by the input component for label font size (MarsUI UI/Para/medium: body_1 13px). |
--ki-input-label-font-weight | font weight used by the input component for label font weight. |
--ki-input-label-gap | dimension used by the input component for label gap. |
--ki-input-label-hint-fg | color used by the input component for the label hint after the label text (spec 047: the supporting-text role, a declared a11y deviation from the MarsUI Input_label support text Text/low_em, which reads 2.8-3.13:1 on the onmars light surfaces; under more contrast it strengthens with every other supporting text). |
--ki-input-label-hint-gap | dimension used by the input component for the gap between the label text and the label hint (MarsUI Input_label: Space/xs 4px). |
--ki-input-label-line-height | dimension used by the input component for label line height (MarsUI line_height/para 20px). |
--ki-input-label-padding-inline | dimension used by the input component for label padding inline (MarsUI Input_label row 2px inset aligning the label ink with the cell radius). |
--ki-input-lg-font-size | dimension used by the input component for lg font size: body-2 (Input-cell 8016:286 lg). |
--ki-input-lg-height | dimension used by the input component for lg height (Input-cell 8016:286 lg: 48px; consumed as min-block-size, spec 050). |
--ki-input-lg-icon-size | dimension used by the input component for the lg icon box (Input-cell 8016:286 lg icon 20px). |
--ki-input-lg-label-font-size | dimension used by the input component for the lg label font size: the Input-label 12021:6068 lg step, body-2 (spec 050 D4). |
--ki-input-lg-label-line-height | dimension used by the input component for the lg label line height (body-2, Input-label lg; spec 050 D4). |
--ki-input-lg-line-height | dimension used by the input component for lg line height (body-2, Input-cell 8016:286 lg). |
--ki-input-lg-padding-inline | dimension used by the input component for lg padding inline (Input-cell 8016:286 lg binds Space/xl, 12px). |
--ki-input-lg-radius | dimension used by the input component for lg radius (Input-cell 8016:286 lg binds Radius/small-component/lg). |
--ki-input-lg-text-padding-inline | dimension used by the input component for the lg inline padding of the native control (Input-cell 8016:286 lg Text_wrap binds Space/xs, 4px; medium uses the gap token). |
--ki-input-line-height | dimension used by the input component for line height. |
--ki-input-outlined-bg | Surface of an outlined text field. |
--ki-input-outlined-border | Full outline of an enabled outlined text field. |
--ki-input-outlined-fg | Entered text on an outlined field. |
--ki-input-outlined-placeholder-fg | Placeholder on an outlined field. |
--ki-input-outlined-radius | Corner radius of an outlined text field. |
--ki-input-padding-inline | dimension used by the input component for padding inline. |
--ki-input-radius | dimension used by the input component for radius (MarsUI Radius/component/radius_md 10px, the md Input_cell binding; component ramp so personality modes reach it). |
--ki-input-readonly-bg | color used by the input component for readonly background (retires the deprecated ki.surface.raised alias; same resolved value). |
--ki-input-readonly-border | color used by the input component for readonly border. |
--ki-input-readonly-fg | color used by the input component for readonly foreground. |
--ki-input-readonly-label-fg | color used by the input component for readonly label foreground (MarsUI label is Text/med_em in every non-disabled state — active and danger included; the danger signal lives in the hint). |
--ki-input-readonly-placeholder-fg | color used by the input component for readonly placeholder foreground (Text/med_em — a declared a11y deviation from the MarsUI placeholder binding Text/low_em, which reads 2.66-3.13:1 on the light field fills; a placeholder is not the accessible name but it is still text, so the contrast gate holds it to 4.5:1). |
--ki-input-rest-bg | color used by the input component for rest background (MarsUI Input_field rest fill Surface/s2: the fill identifies the field, not the outline). |
--ki-input-rest-border | color used by the input component for rest border. |
--ki-input-rest-fg | color used by the input component for rest foreground. |
--ki-input-rest-label-fg | color used by the input component for rest label foreground (MarsUI label is Text/med_em in every non-disabled state — active and danger included; the danger signal lives in the hint). |
--ki-input-rest-placeholder-fg | color used by the input component for rest placeholder foreground (Text/med_em — a declared a11y deviation from the MarsUI placeholder binding Text/low_em, which reads 2.66-3.13:1 on the light field fills; a placeholder is not the accessible name but it is still text, so the contrast gate holds it to 4.5:1). |
--ki-input-sm-font-size | dimension used by the input component for sm font size: caption-2 (Input-cell 8016:286 sm). |
--ki-input-sm-height | dimension used by the input component for sm height (Input-cell 8016:286 sm: 32px; consumed as min-block-size, spec 050). |
--ki-input-sm-icon-size | dimension used by the input component for the sm icon box (Input-cell 8016:286 sm icon 16px). |
--ki-input-sm-label-font-size | dimension used by the input component for the sm label font size: the Input-label 12021:6068 sm step, caption-2 (spec 050 D4). |
--ki-input-sm-label-line-height | dimension used by the input component for the sm label line height (caption-2, Input-label sm; spec 050 D4). |
--ki-input-sm-line-height | dimension used by the input component for sm line height (caption-2, Input-cell 8016:286 sm). |
--ki-input-sm-padding-inline | dimension used by the input component for sm padding inline (Input-cell 8016:286 sm binds Space/md, 8px). |
--ki-input-sm-radius | dimension used by the input component for sm radius (Input-cell 8016:286 sm binds Radius/small-component/sm). |
--ki-input-sm-text-padding-inline | dimension used by the input component for the sm inline padding of the native control (Input-cell 8016:286 sm Text_wrap binds Space/xs, 4px; medium uses the gap token). |
--ki-input-xl-font-size | dimension used by the input component for xl font size: title-2 (Input-cell 8016:286 xl). |
--ki-input-xl-height | dimension used by the input component for xl height (Input-cell 8016:286 xl: 56px; consumed as min-block-size, spec 050). |
--ki-input-xl-icon-size | dimension used by the input component for the xl icon box (Input-cell 8016:286 xl icon 24px). |
--ki-input-xl-label-font-size | dimension used by the input component for the xl label font size: the Input-label 12021:6068 lg step, body-2 (spec 050 D4). |
--ki-input-xl-label-line-height | dimension used by the input component for the xl label line height (body-2, Input-label lg; spec 050 D4). |
--ki-input-xl-line-height | dimension used by the input component for xl line height (title-2, Input-cell 8016:286 xl). |
--ki-input-xl-padding-inline | dimension used by the input component for xl padding inline (Input-cell 8016:286 xl binds Space/2xl, 14px). |
--ki-input-xl-radius | dimension used by the input component for xl radius (Input-cell 8016:286 xl binds Radius/small-component/xl). |
--ki-input-xl-text-padding-inline | dimension used by the input component for the xl inline padding of the native control (Input-cell 8016:286 xl Text_wrap binds Space/sm, 6px; medium uses the gap token). |
--ki-input-xs-font-size | dimension used by the input component for xs font size: caption-2 (Input-cell 8016:286 xs). Figma draws caption_1, 10px; caption_2, 12px, is the smallest text the library ships (spec 050 D7). |
--ki-input-xs-height | dimension used by the input component for xs height (Input-cell 8016:286 xs: 24px; consumed as min-block-size, spec 050). |
--ki-input-xs-icon-size | dimension used by the input component for the xs icon box (Input-cell 8016:286 xs icon 14px). |
--ki-input-xs-label-font-size | dimension used by the input component for the xs label font size: the Input-label 12021:6068 sm step, caption-2 (spec 050 D4). |
--ki-input-xs-label-line-height | dimension used by the input component for the xs label line height (caption-2, Input-label sm; spec 050 D4). |
--ki-input-xs-line-height | dimension used by the input component for xs line height (caption-2, Input-cell 8016:286 xs). |
--ki-input-xs-padding-inline | dimension used by the input component for xs padding inline (Input-cell 8016:286 xs binds Space/sm, 6px). |
--ki-input-xs-radius | dimension used by the input component for xs radius (Input-cell 8016:286 xs binds Radius/small-component/xs). |
--ki-input-xs-text-padding-inline | dimension used by the input component for the xs inline padding of the native control (Input-cell 8016:286 xs Text_wrap binds Space/xxs, 2px; medium uses the gap token). |
--ki-motion-duration-fast | Fast interaction transition duration. |
--ki-motion-easing-out | Decelerating interaction transition easing curve. |
--ki-motion-easing-standard | Standard interaction transition easing curve. |
--ki-text-danger-high-em | semantic color for text danger 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-line-height-body-2 | semantic dimension for typography line height body 2. |
--ki-typography-line-height-caption-2 | semantic dimension for typography line height caption 2. |
--ki-typography-size-body-2 | semantic dimension for typography size body 2. |
--ki-typography-size-caption-2 | semantic dimension for typography size caption 2. |
--ki-typography-visually-hidden-size | Nonzero edge for clipped text available to assistive technology. |
--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. |
Accessibility
Section titled “Accessibility”placeholder is never a label substitute — the label prop is the
accessible name. Native input events cross the shadow boundary on their
own; the change event is re-dispatched composed at the host, so listen
exactly as on a native input. For multiline text use
ki-textarea; for predefined choices use
ki-select.