Skip to content
Kimenpre-v1documentation home
Color scheme

ki-textarea

A token-styled multiline text field with native form semantics — comments, descriptions, messages, delivery notes.

Theme for this example
Color scheme for this example
<ki-textarea label="Delivery notes" name="notes" rows="3" placeholder="Gate code, preferred entrance…"></ki-textarea>
Theme for this example
Color scheme for this example
Send
<form onsubmit="event.preventDefault()">
<ki-textarea label="Feedback" name="feedback" required rows="4"></ki-textarea>
<ki-button variant="primary">Send</ki-button>
</form>

Initial text is declared through the value attribute; element text content is ignored:

Theme for this example
Color scheme for this example
<ki-textarea label="Bio" value="Design systems, gates, and coffee."></ki-textarea>

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.

minlength uses native minimum-length validation. The textarea keeps edits past maxlength and blocks submission until the value fits. With a maximum, show-count adds the current length to the field description and announces when the user reaches or exceeds the limit. Use maxlength-error-text to localize the default length error.

Theme for this example
Color scheme for this example
<ki-textarea label="Bio" appearance="outlined" minlength="3" maxlength="24" show-count help-text="Keep it short" value="Designer and front-end developer"></ki-textarea>
<ki-textarea label="Short bio" appearance="filled" maxlength="12" show-count help-text="Keep it short" value="Designs generative interfaces."></ki-textarea>

When to use: free-form text longer than one line, such as comments, descriptions, messages, delivery notes, or addresses when paired with a matching autocomplete purpose.

When not to use: single-line values (ki-input), constrained choices, rich or formatted text editing, or search boxes. Agent note: initial text is declared through the value attribute; element text content is ignored. Enter inserts a line break and never submits the enclosing form, the inverse of ki-input.

Properties & attributes

AttributePropertyTypeDefaultDescription
appearanceappearance"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.
autocompleteautocompletestring | undefined–Autofill detail token forwarded to the native textarea. When to use: expose entry purpose such as street-address when available. When NOT to use: omit when no valid autofill purpose applies.
disableddisabledbooleanfalseDisables editing, focus, validation and form-data contribution. When to use: make a field temporarily unavailable. When NOT to use: do not use disabled for readonly review text that should submit.
error-texterrorTextstring | undefined–Message shown in place of the help text once the person's answer fails a constraint (required or a length limit), and the field's validationMessage. Say how to fix the answer. 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-texthelpTextstring | undefined–One line of help under the field, read with it as its description: what to write, or how long. 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.
labellabelstring–Visible label rendered by the component and used as the accessible name. When to use: always provide a concise label for the requested long-form text. When NOT to use: do not substitute placeholder text for the label.
label-hintlabelHintstring | 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 length limits in it (use help-text), errors (use error-text), or a repeat of the label.
maxlengthmaxlengthnumber | undefined–Soft maximum in UTF-16 code units. Longer user edits and assigned values are preserved and fail form validation with validity.tooLong. When to use: let people revise an over-limit draft without losing text.
maxlength-error-textmaxlengthErrorTextstring | undefined'Shorten the text to fit the character limit.'Localized message for an over-limit value. error-text and setCustomValidity() take precedence. When to use: translate the soft maximum message for the page language.
minlengthminlengthnumber | 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.
namenamestring | undefined–Form-data key used when the textarea submits with a form. When to use: provide for fields whose text must be included in FormData. When NOT to use: omit for display-only or client-only fields.
placeholderplaceholderstring | undefined–Hint shown while the textarea is empty. When to use: add an example or short formatting hint. When NOT to use: do not use placeholder as the accessible name or required instruction.
readonlyreadonlybooleanfalseMakes the textarea focusable and selectable while rejecting edits. When to use: show submitted or policy text that should still be included in form data. When NOT to use: do not use readonly to remove a field from submission; use disabled.
requiredrequiredbooleanfalseRequires a non-empty value before form submission. When to use: mark mandatory long-form text. When NOT to use: do not pair with readonly expecting it to block; readonly fields are validation exempt like native textareas.
rowsrowsnumber2Visible line count. Invalid, non-numeric, zero, or negative values fall back to 2; no auto-grow or user resize handle exists in v1. When to use: set the stable multiline height needed by the layout. When NOT to use: do not use rows as a responsive size axis.
show-countshowCountboolean | undefinedfalseShows 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.
sizesize"lg" | "md" | "sm" | "xl" | "xs"'md'Token-backed field size (--ki-textarea-{size}-* tokens): padding, radius and text; the label and help text follow in three steps. The height stays rows lines. An unrecognized value matches no style rule and keeps the medium metrics. When to use: match the size of the 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.
valuevaluestring''Live current text. The value attribute declares the reset default; element text content is ignored. Programmatic assignments replace the display and emit no events. When to use: preload or read free-form text, line breaks included. When NOT to use: do not put initial text between the element tags.

Events

EventDetail typeDescription
changeEventFired when the user commits an edited value (on blur, with native textarea timing), 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.

CSS parts

PartDescription
countCurrent character count and maximum at the end of the field message row.
errorError 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.
fieldThe enclosure wrapper.
helpHelp line under the field, read as the field's description.
labelRendered visible label and accessible-name source.
label-hintThe label-hint text after the label text, inside the label and part of the accessible name; rendered only while a hint is set.
textareaInternal native multiline control.

CSS custom properties

The public styling contract of ki-textarea: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--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-input-appearance-border-widthResting stroke width of both explicit text field appearances.
--ki-input-count-bgResting character count surface over the surrounding page.
--ki-input-count-fgCharacter count when the value fits the maximum.
--ki-input-count-over-bgOver-limit character count surface over the surrounding page.
--ki-input-count-over-fgCharacter count when the value exceeds the maximum.
--ki-input-filled-backdrop-filterOptional backdrop filter of a filled field.
--ki-input-filled-bgSurface of a filled text field.
--ki-input-filled-bg-imageOptional background image of a filled field.
--ki-input-filled-fgEntered text on a filled field.
--ki-input-filled-focus-widthStroke width of the block-end indicator while focused.
--ki-input-filled-indicatorContinuous block-end edge of an enabled filled text field.
--ki-input-filled-placeholder-fgPlaceholder on a filled field.
--ki-input-filled-radiusBlock-start corner radius of a filled text field.
--ki-input-label-gapdimension used by the input component for label gap.
--ki-input-outlined-bgSurface of an outlined text field.
--ki-input-outlined-borderFull outline of an enabled outlined text field.
--ki-input-outlined-fgEntered text on an outlined field.
--ki-input-outlined-placeholder-fgPlaceholder on an outlined field.
--ki-input-outlined-radiusCorner radius of an outlined text field.
--ki-motion-duration-fastFast interaction transition duration.
--ki-motion-easing-outDecelerating interaction transition easing curve.
--ki-text-danger-high-emsemantic color for text danger 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-textarea-border-block-end-widthdimension used by the textarea component for border block end width.
--ki-textarea-border-block-start-widthdimension used by the textarea component for border block start width.
--ki-textarea-border-inline-end-widthdimension used by the textarea component for border inline end width.
--ki-textarea-border-inline-start-widthdimension used by the textarea component for border inline start width.
--ki-textarea-disabled-bgcolor used by the textarea component for disabled background (MarsUI Surface/disabled_base_em Gray/100; aligned with ki-input).
--ki-textarea-disabled-bordercolor used by the textarea component for disabled border.
--ki-textarea-disabled-fgcolor used by the textarea component for disabled foreground.
--ki-textarea-disabled-label-fgcolor used by the textarea component for disabled label foreground.
--ki-textarea-disabled-placeholder-fgcolor used by the textarea component for disabled placeholder foreground.
--ki-textarea-focus-bgcolor used by the textarea component for focus background (MarsUI active fill switches to white / dark s2 — modeled with the scheme ladder s0).
--ki-textarea-focus-fgcolor used by the textarea component for focus foreground.
--ki-textarea-focus-label-fgcolor used by the textarea component for focus label foreground (MarsUI label is Text/med_em in every non-disabled state; matches ki-input).
--ki-textarea-focus-placeholder-fgcolor used by the textarea 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-textarea-focus-ring-colorcolor used by the textarea component for focus ring color.
--ki-textarea-focus-ring-offsetdimension used by the textarea component for focus ring offset.
--ki-textarea-focus-ring-shadowshadow used by the textarea 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-textarea-focus-ring-widthdimension used by the textarea component for focus ring width.
--ki-textarea-font-sizedimension used by the textarea component for font size.
--ki-textarea-font-size-touchdimension used by the textarea 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-textarea-font-weightfont weight used by the textarea component for font weight.
--ki-textarea-hover-bgcolor used by the textarea component for hover background (MarsUI hover = s2 + Black/3 overlay; s3 is the nearest token).
--ki-textarea-hover-bordercolor used by the textarea component for hover border.
--ki-textarea-hover-fgcolor used by the textarea component for hover foreground.
--ki-textarea-hover-label-fgcolor used by the textarea component for hover label foreground (MarsUI label is Text/med_em in every non-disabled state; matches ki-input).
--ki-textarea-hover-placeholder-fgcolor used by the textarea 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-textarea-invalid-bgcolor used by the textarea component for invalid background (MarsUI danger keeps the white active fill — no tinted slab; ring and hint carry the signal).
--ki-textarea-invalid-bordercolor used by the textarea component for invalid border.
--ki-textarea-invalid-fgcolor used by the textarea component for invalid foreground.
--ki-textarea-invalid-label-fgcolor used by the textarea component for invalid label foreground (MarsUI label is Text/med_em in every non-disabled state; matches ki-input).
--ki-textarea-invalid-placeholder-fgcolor used by the textarea 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-textarea-invalid-ringshadow used by the textarea component for the persistent invalid ring (MarsUI Focus/danger: 3px danger-500 alpha spread; applied as box-shadow while :state(user-invalid)).
--ki-textarea-label-font-sizedimension used by the textarea component for label font size (MarsUI UI/Para/medium: body_1 13px).
--ki-textarea-label-font-weightfont weight used by the textarea component for label font weight.
--ki-textarea-label-gapdimension used by the textarea component for label gap.
--ki-textarea-label-hint-fgcolor used by the textarea 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-textarea-label-hint-gapdimension used by the textarea component for the gap between the label text and the label hint (MarsUI Input_label: Space/xs 4px).
--ki-textarea-label-line-heightdimension used by the textarea component for label line height (MarsUI line_height/para 20px).
--ki-textarea-label-padding-inlinedimension used by the textarea component for label padding inline (MarsUI Input_label row 2px inset aligning the label ink with the cell radius; matches ki-input).
--ki-textarea-lg-font-sizedimension used by the textarea component for lg font size: body-2 (Input-cell 8016:286 Type=textarea lg).
--ki-textarea-lg-label-font-sizedimension used by the textarea component for the lg label font size: the Input-label 12021:6068 lg step, body-2 (spec 050 D4).
--ki-textarea-lg-label-line-heightdimension used by the textarea component for the lg label line height (body-2, Input-label lg; spec 050 D4).
--ki-textarea-lg-line-heightdimension used by the textarea component for lg line height (body-2, Input-cell 8016:286 Type=textarea lg).
--ki-textarea-lg-padding-blockdimension used by the textarea component for lg padding block (Input-cell 8016:286 Type=textarea lg binds Space/lg, 10px).
--ki-textarea-lg-padding-inlinedimension used by the textarea component for lg padding inline (Input-cell 8016:286 Type=textarea lg binds Space/xl, 12px).
--ki-textarea-lg-radiusdimension used by the textarea component for lg radius (Input-cell 8016:286 Type=textarea lg binds Radius/small-component/lg).
--ki-textarea-line-heightdimension used by the textarea component for line height.
--ki-textarea-min-targetdimension used by the textarea component for min target.
--ki-textarea-padding-blockdimension used by the textarea component for padding block (Input-cell textarea md 8018:176: Space/md 8px).
--ki-textarea-padding-inlinedimension used by the textarea component for padding inline (MarsUI 96px md textarea: 12px ink inset).
--ki-textarea-radiusdimension used by the textarea component for radius (MarsUI Radius/component/radius_md 10px for the md size; component ramp so personality modes reach it).
--ki-textarea-readonly-bgcolor used by the textarea component for readonly background.
--ki-textarea-readonly-bordercolor used by the textarea component for readonly border.
--ki-textarea-readonly-fgcolor used by the textarea component for readonly foreground.
--ki-textarea-readonly-label-fgcolor used by the textarea component for readonly label foreground (MarsUI label is Text/med_em in every non-disabled state; matches ki-input).
--ki-textarea-readonly-placeholder-fgcolor used by the textarea 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-textarea-rest-bgcolor used by the textarea component for rest background (MarsUI textarea fill Surface/s2).
--ki-textarea-rest-bordercolor used by the textarea component for rest border.
--ki-textarea-rest-fgcolor used by the textarea component for rest foreground.
--ki-textarea-rest-label-fgcolor used by the textarea component for rest label foreground (MarsUI label is Text/med_em in every non-disabled state; matches ki-input).
--ki-textarea-rest-placeholder-fgcolor used by the textarea 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-textarea-sm-font-sizedimension used by the textarea component for sm font size: caption-2 (Input-cell 8016:286 Type=textarea sm).
--ki-textarea-sm-label-font-sizedimension used by the textarea component for the sm label font size: the Input-label 12021:6068 sm step, caption-2 (spec 050 D4).
--ki-textarea-sm-label-line-heightdimension used by the textarea component for the sm label line height (caption-2, Input-label sm; spec 050 D4).
--ki-textarea-sm-line-heightdimension used by the textarea component for sm line height (caption-2, Input-cell 8016:286 Type=textarea sm).
--ki-textarea-sm-padding-blockdimension used by the textarea component for sm padding block (Input-cell 8016:286 Type=textarea sm binds Space/md, 8px).
--ki-textarea-sm-padding-inlinedimension used by the textarea component for sm padding inline (Input-cell 8016:286 Type=textarea sm binds Space/md, 8px).
--ki-textarea-sm-radiusdimension used by the textarea component for sm radius (Input-cell 8016:286 Type=textarea sm binds Radius/small-component/sm).
--ki-textarea-xl-font-sizedimension used by the textarea component for xl font size: title-2 (Input-cell 8016:286 Type=textarea xl).
--ki-textarea-xl-label-font-sizedimension used by the textarea component for the xl label font size: the Input-label 12021:6068 lg step, body-2 (spec 050 D4).
--ki-textarea-xl-label-line-heightdimension used by the textarea component for the xl label line height (body-2, Input-label lg; spec 050 D4).
--ki-textarea-xl-line-heightdimension used by the textarea component for xl line height (title-2, Input-cell 8016:286 Type=textarea xl).
--ki-textarea-xl-padding-blockdimension used by the textarea component for xl padding block (Input-cell 8016:286 Type=textarea xl binds Space/xl, 12px).
--ki-textarea-xl-padding-inlinedimension used by the textarea component for xl padding inline (Input-cell 8016:286 Type=textarea xl binds Space/2xl, 14px).
--ki-textarea-xl-radiusdimension used by the textarea component for xl radius (Input-cell 8016:286 Type=textarea xl binds Radius/small-component/xl).
--ki-textarea-xs-font-sizedimension used by the textarea component for xs font size: caption-2 (Input-cell 8016:286 Type=textarea xs). Figma draws caption_1, 10px; caption_2, 12px, is the smallest text the library ships (spec 050 D7).
--ki-textarea-xs-label-font-sizedimension used by the textarea component for the xs label font size: the Input-label 12021:6068 sm step, caption-2 (spec 050 D4).
--ki-textarea-xs-label-line-heightdimension used by the textarea component for the xs label line height (caption-2, Input-label sm; spec 050 D4).
--ki-textarea-xs-line-heightdimension used by the textarea component for xs line height (caption-2, Input-cell 8016:286 Type=textarea xs).
--ki-textarea-xs-padding-blockdimension used by the textarea component for xs padding block (Input-cell 8016:286 Type=textarea xs binds Space/md, 8px).
--ki-textarea-xs-padding-inlinedimension used by the textarea component for xs padding inline (Input-cell 8016:286 Type=textarea xs binds Space/sm, 6px).
--ki-textarea-xs-radiusdimension used by the textarea component for xs radius (Input-cell 8016:286 Type=textarea xs binds Radius/small-component/xs).
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-line-height-body-2semantic dimension for typography line height body 2.
--ki-typography-line-height-caption-2semantic dimension for typography line height caption 2.
--ki-typography-size-body-2semantic dimension for typography size body 2.
--ki-typography-size-caption-2semantic dimension for typography size caption 2.
--ki-typography-visually-hidden-sizeNonzero edge for clipped text available to assistive technology.
--ki-typography-weight-body-normalsemantic font weight for typography weight body normal.
--ki-typography-weight-body-semiboldsemantic font weight for typography weight body semibold.

The label prop is the accessible name — mandatory, and placeholder is never a substitute. Enter inserts a line break and never submits the enclosing form — the inverse of ki-input. For single-line values use ki-input; rich or formatted editing is out of scope.

Open ki-textarea in Storybook