TextInput Props

Name	Type	Default	Description
modelValue	string	Required	Input value, normally bound with v-model.
label	string	Required	Visible label. Still names the control when visually hidden.
isLabelHidden	boolean	false	Visually hides the label and description without removing accessible associations.
description	string	—	Helper text between the label and control.
isDisabled	boolean	false	Disables the input. Disabled values are excluded from form submission.
isOptional	boolean	false	Shows an optional indicator and takes precedence over isRequired.
isRequired	boolean	false	Shows a required indicator; TextInput also sets aria-required.
labelIcon	Component	—	Vue icon component before the label. The labelIcon slot takes precedence.
labelTooltip	string	—	Info button beside the label, available on hover, keyboard focus and click.
optionalLabel	string	Optional	Localized optional indicator.
requiredLabel	string	Required	Localized required indicator.
id	string	Generated	Native input ID. Label and description associations update together.
type	'text' | 'password' | 'email'	text	Single-line input type. Use a textarea for multiline content.
size	'sm' | 'md' | 'lg'	md	Neutral heights are 28, 32 and 36px respectively.
isReadOnly	boolean	false	Prevents editing, but remains focusable, undimmed and included in form submission.
disabledMessage	string	—	Disabled reason. Uses aria-disabled and readonly to preserve focus, while blocking edits and excluding the field from submission.
startIcon	Component	—	Decorative leading icon component. The icon slot takes precedence.
status	TextInputStatus	—	Error, warning or success, optionally with message and messageId. Error sets aria-invalid.
statusVariant	'attached' | 'detached' | 'tooltip'	attached	Attached, detached or an icon tooltip. All variants describe the input accessibly.
changeAction	(value: string, event: TextInputChangeEvent) => void | Promise<void>	—	Runs after a value change. A returned Promise automatically drives pending state.
isLoading	boolean	false	External loading state, combined with pending actions without disabling editing.
placeholder	string	—	Empty-value hint. Does not replace the label.
width	number | string	auto	Width of the whole field. Numbers are pixels, CSS strings are used unchanged.
hasClear	boolean	false	Shows a clear button for nonempty editable values and restores input focus after clearing.
hasAutoFocus	boolean	false	Focuses the native input after mounting.
htmlName	string	—	Native name, taking precedence over a forwarded name and removed when disabled.
autoComplete	string	—	Forwarded unchanged to native autocomplete.
clearLabel	string	Clear {label}	Localized clear-button name.
loadingLabel	string	Loading	Localized loading-indicator name.

Status type

interface TextInputStatus {
  type: 'error' | 'warning' | 'success'
  message?: string
  messageId?: string
}

TextInput Slots

Name	Type	Default	Description
icon	() => VNode[]	—	Decorative leading icon, overriding startIcon. Keep interactive controls out of this slot.
end	() => VNode[]	—	Trailing content, including buttons. Consumers provide accessible names.
labelIcon	() => VNode[]	—	Decorative label icon, overriding the labelIcon prop.

TextInput Events

Name	Type	Default	Description
update:modelValue	value: string	—	v-model update, before change and changeAction.
change	value: string, event: TextInputChangeEvent	—	Emitted after each committed edit or clear. event.preventDefault() skips changeAction without undoing the model update.
enter	event: KeyboardEvent	—	Enter outside IME composition. Canceled keydown events suppress it.
keydown	event: KeyboardEvent	—	Native keyboard event. PreventDefault() can suppress enter.
clear	event: MouseEvent	—	Clear-button activation. Still emits update:modelValue and change and runs an uncanceled action.
actionError	error: unknown, value: string, event: TextInputChangeEvent	—	Emitted after a synchronous throw or Promise rejection. Pending is cleaned automatically.

TextInputChangeEvent

type TextInputChangeEvent = CustomEvent<{
  value: string
  originalEvent: Event
}>

• Native input events are usually not cancelable.
• change supplies a cancelable component event.
• event.detail.value contains the new value.
• event.detail.originalEvent contains the original event.
• changeAction and actionError receive the same component event.

The original event type depends on the action:

Action	Type
Enter text	InputEvent
Confirm input method composition	CompositionEvent
Click the clear button	MouseEvent

Async actions

changeAction receives the new value and component event. Returning a Promise displays a loading indicator.

• Editing: the input remains editable while saving. Clearing the value also runs changeAction.
• Loading: aria-busy stays true while any action is unfinished. It clears after all actions settle, including rejected actions.
• Value updates: new values from the parent take precedence over temporary display values.
• Concurrent saves: cancel older requests or check request versions in your application to prevent stale results from overwriting newer values.
• Errors: handle @action-error to show a message. To roll back, update the value bound with v-model.

Template refs

Template refs expose these properties and methods:

• element: HTMLInputElement | null: the native input element, or null before mounting.
• focus(options?: FocusOptions): focuses the input.
• blur(): removes focus from the input.
• select(): selects all input text.

Native attributes

• maxlength, minlength, pattern, required, form, aria-*, data-* and native event listeners are forwarded to the native input.
• class and style apply to the input wrapper; width applies to the whole Field.
• The component manages value, type, disabled, readonly, autofocus and core ARIA state. Use the corresponding component props.
• aria-describedby and aria-labelledby merge with the component's internal association IDs.

Disabled and read-only states

• Disabled without a reason: native disabled prevents editing, focus and submission of the field.
• Disabled with disabledMessage: aria-disabled and readonly preserve focus so the reason can be discovered. The component removes name and blocks edits and clearing.
• Read-only: the input remains focusable, allows copying and is included in FormData.
• Disabled takes precedence when both states are set.

Theme

Add a class to the component to override theme variables:

<TextInput v-model="email" class="my-input" label="Email" />

.my-input {
  --astryx-input-focus: #10b981;
  --astryx-radius-element: 8px;
}

Appearance and size

• --astryx-input-background: input background color.
• --astryx-input-border: default border color.
• --astryx-input-focus: focus border color when no validation status is set.
• --astryx-radius-element: input corner radius.
• --astryx-input-height-sm: small height; Neutral defaults to 28px.
• --astryx-input-height-md: medium height; Neutral defaults to 32px.
• --astryx-input-height-lg: large height; Neutral defaults to 36px.

Validation states

Each state provides three variables for the border and icon, message text, and message background:

• Error: --astryx-input-error, --astryx-input-error-foreground, --astryx-input-error-background.
• Warning: --astryx-input-warning, --astryx-input-warning-foreground, --astryx-input-warning-background.
• Success: --astryx-input-success, --astryx-input-success-foreground, --astryx-input-success-background.

Override status variables on a parent containing the whole field to style both the input and its status message.

Color mode

• Neutral selects its colors from CSS color-scheme.
• Set data-astryx-color-mode="light" on the root element or theme container to use light mode.
• Set data-astryx-color-mode="dark" to use dark mode.