TextInput·component·@astryxdesign/core

Text Input

TextInput collects short-form text like names, emails, or search queries. Use it for single-line values where the expected input is brief. Pair it with validation status to guide users through required or formatted fields.

Open in Playground @astryxdesign/core/TextInput

Showcases and examples

7 documented examples

Text Input

TextInput API entry

Open Playground ↗

Preview loads on approachPreview loads on approach

Exact source · text-input-showcase

// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {useState} from 'react';
import {TextInput} from '@astryxdesign/core/TextInput';

export default function TextInputShowcase() {
  const [value, setValue] = useState('');
  return (
    <div style={{width: 300}}>
      <TextInput
        label="Name"
        value={value}
        onChange={setValue}
        placeholder="Enter your name"
      />
    </div>
  );
}

Usage

Always provide a visible label so users know what the field is for. Only hide the label when surrounding context makes it obvious, like a search bar with a magnifying-glass icon.
Use validation status with a message to explain what went wrong: "Email must include @" is better than just turning the border red.
Size the input to match the expected content length so users can gauge how much to type: small for zip codes, medium for names, large for URLs.
Add a clear button for search and filter inputs so users can quickly reset without selecting all text.
Don't use placeholder text as a replacement for a label; placeholders disappear on focus and are not reliably read by screen readers.
Don't use TextInput for multi-line content like comments or descriptions; use TextArea instead.
Don't mark every field as required; only flag mandatory fields so users are not overwhelmed by validation errors.
Don't wrap a disabled TextInput in Tooltip to explain why it's disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

Typed props

Prop	Type and behavior
`type`	`'text' \| 'password' \| 'email'` · default 'text' The HTML input type.
`label`	`string` · required Label text for the input: always rendered for accessibility.
`value`	`string` · required Current value of the input.
`onChange`	`(value: string, e: ChangeEvent<HTMLInputElement>) => void` Callback fired when the input value changes.
`changeAction`	`(value: string, e: ChangeEvent<HTMLInputElement>) => void \| Promise<void>` Async action fired after onChange (if not prevented). Triggers optimistic update and shows a loading spinner while pending.
`size`	`'sm' \| 'md' \| 'lg'` · default 'md' Size variant of the input.
`isLabelHidden`	`boolean` · default false Visually hides the label while keeping it accessible to screen readers.
`description`	`string` Description text displayed between the label and input.
`isOptional`	`boolean` · default false Displays an "Optional" indicator next to the label. Mutually exclusive with isRequired.
`isRequired`	`boolean` · default false Displays a "Required" indicator next to the label and sets aria-required. Mutually exclusive with isOptional.
`onEnter`	`() => void` Callback fired when the user presses the Enter key. IME-safe: Enter used to commit a Japanese/Chinese/Korean conversion does not fire it.
`onKeyDown`	`(e: KeyboardEvent<HTMLInputElement>) => void` Callback fired on keydown events on the input.
`isDisabled`	`boolean` · default false Disables the input, preventing interaction and dimming the element.
`isReadOnly`	`boolean` · default false Makes the input read-only: the value is shown at full opacity and still submits with the form, but cannot be edited. Unlike isDisabled, a read-only input is not dimmed and stays in the tab order. isDisabled takes precedence when both are set.
`disabledMessage`	`string` Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (the field becomes read-only). Use this instead of wrapping a disabled TextInput in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.
`isLoading`	`boolean` · default false Puts the input in a loading state, showing a spinner and setting aria-busy.
`placeholder`	`string` Placeholder text shown when the input is empty.
`labelTooltip`	`string` Tooltip text displayed in an info icon at the end of the label.
`startIcon`	`IconType` SVG icon component displayed at the start of the input. See `astryx docs icons` for valid semantic names.
`status`	`{type: 'error' \| 'warning' \| 'success', message?: string}` Validation status: applies a colored border and status icon. If message is provided, displays a floating message below the input. Error type also sets aria-invalid.
`statusVariant`	`'attached' \| 'detached' \| 'tooltip'` · default 'attached' How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon.
`hasClear`	`boolean` · default false Shows a clear (×) button when the input has a value. Clicking it clears the value and returns focus to the input.
`hasAutoFocus`	`boolean` · default false Automatically focuses the input on mount.
`htmlName`	`string` The HTML name attribute for the input, useful for form submissions.
`width`	`SizeValue` Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.
`autoComplete`	`string` The native autocomplete attribute, forwarded to the input unchanged. Does not affect the controlled value.

Anatomy

Label · required

Text that identifies the field. Always rendered for accessibility even when visually hidden.

Description · optional

Helper text between the label and the input that provides additional context or formatting hints.

Start icon · optional

A leading icon inside the input that hints at the expected content, like a magnifying glass for search.

Placeholder · optional

Hint text shown when the input is empty. Disappears on focus.

Clear button · optional

A trailing × button that resets the value and returns focus to the input.

Spinner · optional

Loading indicator that appears during async actions like server-side validation.

Status icon · optional

A trailing icon (error, warning, or success) that communicates validation state.

Theming

Targets

astryx-text-input

Visual props: size, status

States: disabled, readonly