Text Field

Overview

Text fields allow users to enter and edit text within forms, dialogs, and other interfaces. They provide a structured way to collect user input with clear labeling, validation, and formatting support to ensure data quality and usability.

Usage

forge-text-field wraps a child <input> or <textarea> and an optional <label>, handling layout and state through variant, theme, shape, density, label-position, invalid, required, optional, and disabled. For a fixed set of choices, reach for a select or autocomplete instead; for freeform, removable entries like tags or recipients, use a chip field.

Rules

Variant

Set variant to outlined (the default), plain, tonal, filled, or raised to match the field to its surrounding context.

<forge-text-field variant="plain">
  <label slot="label">
    Plain
  </label>
  <input type="text" />
</forge-text-field>
<forge-text-field variant="outlined">
  <label slot="label">
    Outlined
  </label>
  <input type="text" />
</forge-text-field>
<forge-text-field variant="tonal">
  <label slot="label">
    Tonal
  </label>
  <input type="text" />
</forge-text-field>
<forge-text-field variant="filled">
  <label slot="label">
    Filled
  </label>
  <input type="text" />
</forge-text-field>
<forge-text-field variant="raised">
  <label slot="label">
    Raised
  </label>
  <input type="text" />
</forge-text-field>

Label position

Set label-position to control where the label sits relative to the input: inset (the default) floats it inside the field, block-start places it above, inline-start and inline-end place it beside the field, and none hides it. Only use none for a search or filter field, and give the <input> an aria-label so it still has an accessible name.

<forge-text-field label-position="block-start" class="max-w-[500px]">
  <label slot="label" for="forge-input-7i1qj">
    Label
  </label>
  <input type="text" id="forge-input-7i1qj">
</forge-text-field>

<forge-text-field label-position="inline-start" class="max-w-[500px]">
  <label slot="label" for="forge-input-n5xb7">
    Label
  </label>
  <input type="text" id="forge-input-n5xb7">
</forge-text-field>

Helper text and validation

Slot support text in the helper-text slot, set required for a required field, and set invalid to swap in error text describing the fix.

<forge-text-field required>
  <input required />
</forge-text-field>

<forge-text-field>
  <label slot="label">
    Email
  </label>
  <input type="email" />
  <span slot="support-text">
    We'll only use this to send a receipt.
  </span>
</forge-text-field>
<forge-text-field required>
  <label slot="label">
    Full name
  </label>
  <input type="text" />
</forge-text-field>
<forge-text-field invalid>
  <label slot="label">
    Email
  </label>
  <input type="email" value="not-an-email" />
  <span slot="support-text">
    Enter a valid email, like name@example.com.
  </span>
</forge-text-field>

Multiline

Slot a <textarea> instead of an <input> for longer, multi-line responses. Prefer it over letting a single-line input grow, and size it to fit within mobile screen heights.

<forge-text-field class="max-w-[500px]">
  <label slot="label" for="forge-input-wqhug">
    Label
  </label>
  <textarea id="forge-input-wqhug">
  </textarea>
</forge-text-field>

Clear button

Set show-clear to add a button that clears the field’s value, appearing once the field has a value.

<forge-text-field show-clear>
  <label slot="label">
    Search
  </label>
  <input type="text" value="Prefilled value" />
</forge-text-field>

Leading and trailing content

Slot an icon or short text in the start slot to render it before the input, or in the end slot to render it after, like a unit suffix.

Search and filter fields

A search or filter field is the one place a field may go without a visible label. Set label-position="none", put a search icon in the start slot, set show-clear, and use a short placeholder like “Search” or “Filter by name” in place of the label. Give the <input> an aria-label, since the placeholder isn’t an accessible name.

<forge-text-field label-position="none" show-clear>
  <forge-icon slot="start" name="search"></forge-icon>
  <input type="search" placeholder="Search" aria-label="Search" />
</forge-text-field>

Every other form field keeps a visible label and doesn’t use a placeholder.

Disabled and readonly

Set disabled to exclude the field from the form.

<forge-text-field disabled>
  <label slot="label">
    Disabled
  </label>
  <input type="text" value="Can't edit this" />
</forge-text-field>