HyTextInput
Usage examples on this page are written for Lit / plain HTML (
<hy-text-input>). The same component ships asHyTextInputin@whitespaceux/harmony-react(native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.
A versatile single-line text input component with enhanced styling and functionality. Supports multiple input types, validation states, icons, and comprehensive accessibility features. Provides a consistent interface for various text input scenarios with built-in error handling. Offers both block (default) and inline layout options — in inline, label sits on the left of the row, input on the right, and helper/error under the control (col 2–end).
Examples
html
<hy-text-input label="Name" placeholder="Enter your name"></hy-text-input>html
<hy-text-input
type="email"
label="Email Address"
placeholder="user@example.com"
helper-text="We'll never share your email with anyone"
required
>
</hy-text-input>Inline layout (dense parameter panels)
Label on the left, input on the right, helper/error below the row. Set --hy-text-input-label-column-width on a wrapping container so stacked inputs align on the left edge.
html
<div style="--hy-text-input-label-column-width: 8rem;">
<hy-text-input layout="inline" label="Name" placeholder="Jane Doe"></hy-text-input>
<hy-text-input layout="inline" label="Email" placeholder="jane@example.com"></hy-text-input>
</div>API
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
focused | focused | boolean | false | Whether the input is currently focused. |
disabled | disabled | boolean | false | Disables the input, preventing user interaction. |
required | required | boolean | false | Marks the input as required for form validation. |
readonly | readonly | boolean | false | Makes the input read-only, preventing user editing. |
error | error | boolean | false | Whether the input is in an error state. |
leadingIcon | leading-icon | string | '' | Icon name from HyIcon component library to display before the input field. Uses the HyIcon component for consistent icon rendering across the design system. |
trailingIcon | trailing-icon | string | '' | Icon name from HyIcon component library to display after the input field. Uses the HyIcon component for consistent icon rendering across the design system. |
size | size | 'small' | 'medium' | 'large' | 'medium' | The size of the input: 'small', 'medium', or 'large'. |
layout | layout | 'block' | 'inline' | 'block' | Row layout: block (default) stacks label above the input; inline puts label on the left and input on the right. Helper/error always sit under the control (col 2–end), never under the label. |
width | width | string | undefined | undefined | Width of the input container. Accepts any valid CSS width value (e.g., '300px', '20rem', '50%'). Caps the input field itself; useful in either layout when the default (fill available space) is too wide. |
label | label | string | '' | The label text displayed above the input (block layout) or to the left (inline layout). |
value | value | string | '' | The current value of the input. |
placeholder | placeholder | string | '' | Placeholder text displayed when the input is empty. |
helperText | helper-text | string | '' | Helper text displayed below the input to provide additional context. |
type | type | 'text' | 'email' | 'password' | 'tel' | 'url' | 'search' | 'number' | 'text' | The input type: 'text', 'email', 'password', 'tel', 'url', 'search', or 'number'. |
name | name | string | '' | The name attribute for form submission. |
autocomplete | autocomplete | string | '' | The autocomplete attribute for browser auto-completion. |
autofocus | autofocus | boolean | false | Marks this input as the auto-focus target. Read by hy-dialog (and other overlay containers) on show to choose which slotted control receives initial focus. Also focuses on first connect when used outside an overlay, matching the native HTML autofocus attribute — but routed through JS so SSR'd HTML doesn't pull focus during hydration. |
autoselect | autoselect | boolean | false | After auto-focus lands, selects the current value so the user can type-to-replace. Pairs with autofocus for rename-style dialogs where the existing name is shown for context but is meant to be overwritten. |
errorMessage | error-message | string | '' | Error message displayed when the input is in an invalid state. |
maxlength | maxlength | number | undefined | — | Maximum number of characters allowed in the input. |
minlength | minlength | number | undefined | — | Minimum number of characters required in the input. |
pattern | pattern | string | '' | Regular expression pattern for input validation. |
inputmode | inputmode | string | '' | Virtual-keyboard hint forwarded to the inner input (inputmode), e.g. numeric for one-time codes so mobile users get the number pad while the type stays text (leading zeros, no spinner). |
form | — | HTMLFormElement | null | — | — |
validity | — | ValidityState | — | — |
validationMessage | — | string | — | — |
Events
| Event | Detail | Description |
|---|---|---|
input | — | Fired when the input value changes. Detail: |
change | — | Fired when the input loses focus after a value change. Detail: |
focus | — | Fired when the input receives focus. Detail: none |
blur | — | Fired when the input loses focus. Detail: none |
Slots
| Slot | Description |
|---|---|
leading-icon | Optional slot for custom leading icon content (overrides leading-icon property) |
trailing-icon | Optional slot for custom trailing icon content (overrides trailing-icon property) |
CSS Parts
| Part | Description |
|---|---|
base | The text input's base wrapper element |
label | The label element |
container | The input container element |
input | The native input element |
leading-icon | The leading icon container |
trailing-icon | The trailing icon container |
helper-text | The helper text element |
error-message | The error message element |
CSS Custom Properties
| Property | Description |
|---|---|
--hy-text-input-background-rest | Background color at rest |
--hy-text-input-border-rest | Border color at rest |
--hy-text-input-border-active | Focused edge color, any focus method. Default: var(--hy-border-brand-rest) |
--hy-text-input-border-hover | Border color on hover |
--hy-text-input-border-danger | Border color for error state |
--hy-text-input-stroke | Border width |
--hy-text-input-radius | Border radius |
--hy-text-input-padding-horizontal | Horizontal padding |
--hy-text-input-padding-vertical-sm | Vertical padding for small size |
--hy-text-input-padding-vertical-md | Vertical padding for medium size |
--hy-text-input-padding-vertical-lg | Vertical padding for large size |
--hy-text-input-gap | Gap between input elements |
--hy-text-input-container-gap | Gap between container sections |
--hy-text-input-font-family | Font family override for the input value text |
--hy-text-input-label-column-width | Width of the label column in layout="inline" mode. No default — set on a wrapping container so stacked inputs align. |
--hy-text-input-height-sm | Outer height for small size variant. Per-component override in the form-control height contract (see .claude/rules/control-heights.md). Default: var(--hy-control-height-sm) |
--hy-text-input-height-md | Outer height for medium size variant. Default: var(--hy-control-height-md) |
--hy-text-input-height-lg | Outer height for large size variant. Default: var(--hy-control-height-lg) |
Methods
focus()
Sets focus on the input.
blur()
Removes focus from the input.
select()
Selects all text in the input.