TextInput

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.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

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.

Usage guidance

• 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.
• Avoid: Don't use placeholder text as a replacement for a label; placeholders disappear on focus and are not reliably read by screen readers.
• Avoid: Don't use TextInput for multi-line content like comments or descriptions; use TextArea instead.
• Avoid: Don't mark every field as required; only flag mandatory fields so users are not overwhelmed by validation errors.
• Avoid: 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.

Theming API

{
  "targets": [
    {
      "className": "astryx-text-input",
      "visualProps": [
        "size",
        "status"
      ],
      "states": [
        "disabled",
        "readonly"
      ]
    }
  ]
}

Anatomy

• Label: Text that identifies the field. Always rendered for accessibility even when visually hidden.
• Description: Helper text between the label and the input that provides additional context or formatting hints.
• Start icon: A leading icon inside the input that hints at the expected content, like a magnifying glass for search.
• Placeholder: Hint text shown when the input is empty. Disappears on focus.
• Clear button: A trailing × button that resets the value and returns focus to the input.
• Spinner: Loading indicator that appears during async actions like server-side validation.
• Status icon: A trailing icon (error, warning, or success) that communicates validation state.

Examples

• Text Input:
• TextInput — Icon: Inputs with a leading icon that hints at the expected content. Use when the icon helps users identify the field faster, like a lock for passwords or an envelope for email.
• TextInput — Search: Search input with a hidden label, start icon, and clear button. Use for toolbar and header search bars where the icon provides sufficient context.
• TextInput — Sizes: Small, medium, and large inputs side by side. Use small in dense UIs like table filters, medium for most forms, and large for prominent single-field pages.
• TextInput — States: Error, warning, and success validation states with status messages. Use to show users what went wrong and how to fix it.
• TextInput — Status variant: The statusVariant prop controls whether the status message is attached to the bordered input (default, overlapping directly below) or detached from it (floating below as a separate element with spacing).
• TextInput — Types: Text, password, and email types plus field-level features: tooltip, required, optional, description, disabled, and loading.

Complete example dependencies

Some examples import optional icons. The per-example install command in the examples list identifies exactly what that example needs. For all examples on this page:

npm install @heroicons/react@2.2.0