# Core/TextField - Design

Single-line text field with optional label and helper text.

The following guidelines are common across text-based inputs ([Core Components — Inputs](https://www.figma.com/design/ejoPUMrdRDAlyc2vyDIWWe/Core-Components?node-id=21133-20423) in Figma).

## Properties

### Label

A label is required for input fields and succinctly describes the field’s purpose. If another text element is acting
as the label—like a section title—ensure the proper ARIA relationships are linked.

### Value

The value is submitted with the form. The value replaces any placeholder text in the field after the first character
is entered.

### Placeholder text

Placeholder text is visible until a character is entered. Because the placeholder text disappears, putting
instructions or requirements as placeholder text is not accessible. Helper text is the preferred method to convey
this information.

### Helper text

Helper text is placed below the field and informs the user of any requirements, disclaimers, and errors. Helper text
is shown persistently but is replaced by error text when an error occurs.

### Layout

There are two layouts available for text fields: **vertical** and **horizontal**. With vertical labels, the content
will shift to keep the cursor in view as the user enters characters. When the field loses focus, the content will
scroll to the beginning. Focusing on the field again returns the user to the end of the content. Horizontal labels
appear on the leading side of the field, and should only be used when space is limited.

## Behavior

### Overflow

Values overflow past the trailing edge of the field. While focused, the content will shift to keep the cursor in
view as the user enters characters. When the field loses focus, the content will scroll to the beginning. Focusing
on the field again returns the user to the end of the content. Generally, text fields should avoid overflow. Use a
text area field for longer entries.

## Content

### Search and filter fields

Search and Filter fields allow a user to enter and clear query strings.

**Clear button:** The clear icon appears when a value is present in the text field. When cleared the icon disappears and
the text input keeps focus.

## Feedback

### Error messages

When a field fails validation, the field’s border displays the attention color. The helper text also displays an
error message to help the user successfully fulfill the field requirements. Error messages are concise and direct,
and replace any previously visible helper text. An error icon is prepended to the helper text to enhance
discoverability.

### Disabled

Disabled fields cannot be modified and cannot gain focus. Values in a disabled field are not submitted as part of
the form.

### Read-only

Read-only fields cannot be modified and cannot gain focus. The value of a read-only field is submitted as part of
the form.

## Accessibility

* **Label:** Provide a visible `label` or associate another element via `aria-labelledby` / `aria-label` so the control has an accessible name. Do not rely on placeholder alone for the name.
* **Instructions and requirements:** Prefer persistent `helperText` (or other visible, associated text) over placeholder for instructions; placeholder disappears and is easy to miss.
* **Errors:** Use `appearance="danger"` with error content in `helperText` so validation state is exposed (`aria-invalid`) and messaging replaces prior helper text.
* **Required:** Set `required` when the field is mandatory so required state is available to assistive technologies.
* **Disabled:** Disabled fields are not interactive; their values are not submitted with native form submission.
* **Read-only:** Read-only values are still submitted; the field is not editable. Native read-only inputs may remain focusable for selection and screen readers—align with your product pattern if focus should be limited.