Text Field

alpha

TextField combines a single-line text input with its visible label and optional supporting content, such as hint text and validation feedback.

Use it for ordinary form fields in contact, authentication, profile, and settings forms. The component manages the relationships between the label, input, hint, and error message so they remain correctly associated for assistive technologies.

Use the lower-level TextInput only when another component or custom composition is responsible for providing the field label and descriptive content.

Full name

Phone number

Include the country calling code.

Email address

Enter an email address in the correct format.

Account ID

Company

Basic usage

Provide a unique id, a visible label, and a name when the field will be submitted with a form.

---
import { TextField } from "@ulubit/ui";
---
<TextField
  id="full-name"
  name="fullName"
  label="Full name"
  autocomplete="name"
/>

The component uses the id to associate the visible label and any hint or error message with the underlying input.

Hint text

Use hint to provide instructions that help users enter the value.

<TextField
  id="phone"
  name="phone"
  type="tel"
  label="Phone number"
  hint="Include the country calling code."
/>

Hint text should explain how to answer rather than repeat the label.

Errors

Use error after the current value has failed validation.

<TextField
  id="email"
  name="email"
  type="email"
  label="Email address"
  error="Enter an email address in the correct format."
/>

The component sets aria-invalid="true" and connects the error message through aria-describedby.

Error messages should explain how the user can correct the value. Do not rely only on the invalid border.

The error message uses the semantic --color-danger token. The underlying TextInput also uses the danger role for its invalid border.

Required fields

The native required attribute is forwarded to the input.

Required and optional fields should be identified consistently at the form level. The component does not automatically add an asterisk or optional label.

Typography and color tokens

TextField uses shared typography and semantic color tokens for its label, hint text, and error message.

The label uses:

color: var(--color-text);
font-weight: var(--font-semibold);
line-height: 1.4;

Hint and error text use the smaller --step--1 type-scale value:

font-size: var(--step--1);
line-height: 1.5;

Their colors reflect their semantic roles:

.ui-text-field-hint {
  color: var(--color-text-muted);
}

.ui-text-field-error {
  color: var(--color-danger);
}

Using --step--1 keeps supporting field text connected to the shared typography scale rather than introducing a separate component-specific font-size token.

When the field is disabled, the label and hint use reduced opacity to reinforce the unavailable state.

The underlying input retains the background, text, border, focus, invalid, disabled, and placeholder tokens documented by TextInput.

API

Property	Type	Default	Description
`id`	`string`	Required	Connects the label, input, hint, and error message.
`label`	`string`	Required	Provides the visible and accessible field label.
`hint`	`string`	—	Adds supplementary instructions before the input.
`error`	`string`	—	Adds a validation message and marks the input invalid.
`type`	`"text" \| "email" \| "password" \| "search" \| "tel" \| "url"`	`"text"`	Defines the text-entry input type.
`inputClass`	`string`	—	Adds a class to the underlying input.
`class`	`string`	—	Adds a class to the field wrapper.
`aria-describedby`	`string`	—	Adds external description IDs to the generated relationships.

Other supported TextInput attributes, including name, autocomplete, required, disabled, readonly, value, placeholder, inputmode, minlength, maxlength, pattern, form, and data-*, are forwarded.

Current limitations

The component does not include:

Automatic validation
Dynamic error announcements
Prefixes or suffixes
Leading or trailing icons
Password visibility controls
Character counters