Input
Overview
A single-line text input that collects user input, supporting standard input attributes, prefix/suffix slots, and clearable functionality. Use it for any short free-text entry — form fields, search boxes, filters. For multi-line text use STextarea; for sensitive values use SPassword; for numeric values use SInputNumber.
Usage
Features
- 📏 6 sizes: xs, sm, md, lg, xl, 2xl
- 🧹 Clearable mode with a hover/focus-revealed clear button (i18n
aria-label) - 🔤
leading/trailingslots for prefix and suffix content - 🔒
disabled/readonlystates with full interaction guards - 📋 Native form submission via a proxied hidden input when
nameis set - ♿ Full accessibility support —
aria-roledescription, clear button naming, axe-clean - 🎯 TypeScript type safety with strict
typeattribute typing
Input component family
- SInput - Base text input component
- SInputClear - Clear button, shown on hover/focus when
clearable
Demos
Basic
100%
modelValue:
Slot
100%
API
Aria Layer
5Input
22 Props1 Emits3 Slots
Props
| Prop | Type | Default | Description |
|---|---|---|---|
class | ClassValue | — | root class |
size | ThemeSize | — | Visual size of the component. |
ui | Partial<InputUi> | — | Per-slot class overrides for the component. |
inputRef | ((el: HTMLInputElement) => void) | — | The function to set the input element. |
clearable | boolean | false | Whether to show the clear trigger. |
controlProps | InputControlProps | — | Properties forwarded to the control element. |
clearProps | InputClearProps | — | Properties forwarded to the clear element. |
defaultValue | string | — | The default value of the input |
modelValue | string | — | The controlled value of the input |
disabled | boolean | — | When `true`, prevents the user from interacting with the input. |
readonly | boolean | — | When `true`, the input is read-only. |
rootProps | BaseProps | — | Properties forwarded to the root element |
name | string | — | The name of the field. Submitted with its owning form as part of a name/value pair. |
required | boolean | — | When `true`, indicates that the user must set the value before the owning form can be submitted. |
id | string | — | Id of the input element |
autofocus | boolean | — | When `true`, the input is auto-focused. |
autocomplete | 'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-time-code' | 'given-name' | 'family-name' | 'organization' | 'street-address' | 'address-level2' | 'postal-code' | 'country' | 'cc-name' | 'cc-number' | 'cc-exp' | 'cc-csc' | 'transaction-amount' | — | The autocomplete attribute of the input.
Supports the HTML autofill tokens (including password-manager values such as
`current-password` / `new-password`), in addition to the `on` / `off` switches. |
maxlength | number | — | The maximum number of characters allowed in the input |
minlength | number | — | The minimum number of characters allowed in the input |
pattern | string | — | The pattern attribute of the input |
placeholder | string | — | The placeholder of the input |
type | InputTypeHTMLAttribute | — | The type of the input element. |
Emits
| Emit Name | Parameters | Description |
|---|---|---|
update:modelValue | string | Emitted when the model value changes. |
Slots
| Slot Name | Parameters | Description |
|---|---|---|
leading | InputCompactSlotProps | Custom content for the leading slot. |
trailing | InputCompactSlotProps | Custom content for the trailing slot. |
clear | InputCompactSlotProps | Custom content for the clear slot. |
InputClear
4 Props1 Emits
Props
| Prop | Type | Default | Description |
|---|---|---|---|
type | ButtonType | 'button' | The type of the button element. Can be one of 'button', 'submit', or 'reset'. |
disabled | boolean | — | Whether the component is disabled. |
asChild | boolean | — | Change the default rendered element for the one passed as a child, merging their props and behavior. |
as | AsTag | Component | 'div' | The element or component this component should render as. Can be overwrite by `asChild` |
Emits
| Emit Name | Parameters | Description |
|---|---|---|
clear | PointerEvent | Emitted when the clear button is clicked. |
InputCompact
19 Props2 Emits3 Slots
Props
| Prop | Type | Default | Description |
|---|---|---|---|
inputRef | ((el: HTMLInputElement) => void) | — | The function to set the input element. |
clearable | boolean | false | Whether to show the clear trigger. |
controlProps | InputControlProps | — | Properties forwarded to the control element. |
clearProps | InputClearProps | — | Properties forwarded to the clear element. |
defaultValue | string | — | The default value of the input |
modelValue | string | — | The controlled value of the input |
disabled | boolean | — | When `true`, prevents the user from interacting with the input. |
readonly | boolean | — | When `true`, the input is read-only. |
rootProps | BaseProps | — | Properties forwarded to the root element |
name | string | — | The name of the field. Submitted with its owning form as part of a name/value pair. |
required | boolean | — | When `true`, indicates that the user must set the value before the owning form can be submitted. |
id | string | — | Id of the input element |
autofocus | boolean | — | When `true`, the input is auto-focused. |
autocomplete | 'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-time-code' | 'given-name' | 'family-name' | 'organization' | 'street-address' | 'address-level2' | 'postal-code' | 'country' | 'cc-name' | 'cc-number' | 'cc-exp' | 'cc-csc' | 'transaction-amount' | — | The autocomplete attribute of the input.
Supports the HTML autofill tokens (including password-manager values such as
`current-password` / `new-password`), in addition to the `on` / `off` switches. |
maxlength | number | — | The maximum number of characters allowed in the input |
minlength | number | — | The minimum number of characters allowed in the input |
pattern | string | — | The pattern attribute of the input |
placeholder | string | — | The placeholder of the input |
type | InputTypeHTMLAttribute | — | The type of the input element. |
Emits
| Emit Name | Parameters | Description |
|---|---|---|
update:modelValue | string | Emitted when the model value changes. |
clear | PointerEvent | Emitted when the clear button is clicked. |
Slots
| Slot Name | Parameters | Description |
|---|---|---|
leading | InputCompactSlotProps | Custom content for the leading slot. |
trailing | InputCompactSlotProps | Custom content for the trailing slot. |
clear | InputCompactSlotProps | Custom content for the clear slot. |
InputControl
InputRoot
15 Props1 Emits
Props
| Prop | Type | Default | Description |
|---|---|---|---|
defaultValue | string | — | The default value of the input |
modelValue | string | — | The controlled value of the input |
disabled | boolean | — | When `true`, prevents the user from interacting with the input. |
readonly | boolean | — | When `true`, the input is read-only. |
rootProps | BaseProps | — | Properties forwarded to the root element |
name | string | — | The name of the field. Submitted with its owning form as part of a name/value pair. |
required | boolean | — | When `true`, indicates that the user must set the value before the owning form can be submitted. |
id | string | — | Id of the input element |
autofocus | boolean | — | When `true`, the input is auto-focused. |
autocomplete | 'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-time-code' | 'given-name' | 'family-name' | 'organization' | 'street-address' | 'address-level2' | 'postal-code' | 'country' | 'cc-name' | 'cc-number' | 'cc-exp' | 'cc-csc' | 'transaction-amount' | — | The autocomplete attribute of the input.
Supports the HTML autofill tokens (including password-manager values such as
`current-password` / `new-password`), in addition to the `on` / `off` switches. |
maxlength | number | — | The maximum number of characters allowed in the input |
minlength | number | — | The minimum number of characters allowed in the input |
pattern | string | — | The pattern attribute of the input |
placeholder | string | — | The placeholder of the input |
type | InputTypeHTMLAttribute | — | The type of the input element. |
Emits
| Emit Name | Parameters | Description |
|---|---|---|
update:modelValue | string | Emitted when the model value changes. |
Notes
Architecture and benchmark differences
VeanUI splits the input into an Aria layer (@vean/aria/input) that owns state, form proxying, and clear-button semantics, and a styled layer (@vean/ui) that owns variants and UnoCSS classes. The Aria InputCompact composes InputRoot / InputControl / InputClear and exposes leading / clear / trailing slots, mirroring the headless/styled split of Radix and differing from single-package libraries such as Ant Design and Element Plus.
| Capability | VeanUI | Ant Design Input | Element Plus Input | Radix TextField |
|---|---|---|---|---|
| Aria/styled split | ✅ | — | — | ✅ |
| Controlled / uncontrolled | ✅ | ✅ | ✅ | ✅ |
| Clear button (hover reveal) | ✅ | ✅ | ✅ | — |
Clear button i18n aria-label | ✅ | ✅ | — | — |
| Prefix / suffix slots | ✅ | ✅ | ✅ | ✅ |
| Native form proxying | ✅ | — | — | — |
| Size variants | ✅ | ✅ | ✅ | — |
showCount counter | — | ✅ | ✅ | — |
error / loading state | — | ✅ | ✅ | — |
Cautions
showCount,error, andloadingstates are not implemented; they are tracked as enhancement backlog.- The clear button only appears on hover or focus (desktop convention); on touch devices ensure a
leading/trailingaffordance if needed. - The root renders
role="group"witharia-roledescription="Input"andspellcheck="false"by design.
FAQ
How do I add a prefix icon or suffix text?
Use the leading and trailing slots. They receive the root context and render inside the input field frame.
Why does the clear button only show on hover?
Clear visibility follows the desktop hover/focus convention (group-hover / group-focus-within). It is intentionally not always visible to keep the input compact and avoid accidental clearing.
How does the input submit its value in a native form?
Pass name — the component renders a visually hidden proxy input carrying the current value, so native form submission and validation work without extra wiring.
How do I limit the input length?
Pass maxlength / minlength; they are forwarded to the native input. A visible counter is not yet provided (tracked as enhancement backlog).