ki-input

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

In a form

label is mandatory — it is the accessible name. The field participates in native form submission:

Subscribe

<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

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>

Slots

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>

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
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.
label	label	string | undefined	–	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.
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.
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).

Slots

Slot	Description
end	Trailing icon or text affix inside the field. Follows writing direction.
start	Leading icon or text affix inside the field. Follows writing direction.

CSS parts

Part	Description
field	Enclosure wrapper for background, border, radius and focus ring.
input	Internal native input that owns entry text, caret and selection.
label	Visible label that provides the accessible name.

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-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-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-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 (MarsUI placeholder Text/low_em; placeholder is not the accessible name, so it sits outside the 4.5:1 text sweep).
--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-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 (MarsUI placeholder Text/low_em; placeholder is not the accessible name, so it sits outside the 4.5:1 text sweep).
--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 (MarsUI placeholder Text/low_em; placeholder is not the accessible name, so it sits outside the 4.5:1 text sweep).
--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-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-line-height	dimension used by the input component for line height.
--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 (MarsUI placeholder Text/low_em; placeholder is not the accessible name, so it sits outside the 4.5:1 text sweep).
--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 (MarsUI placeholder Text/low_em; placeholder is not the accessible name, so it sits outside the 4.5:1 text sweep).
--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-typography-family-body	semantic font family for typography family body.

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.

Workshop

Open ki-input in Storybook