Form inputs

Text field

<forma-text-field>

A labelled native text-like input (text, email, password, URL, tel, number) with optional description, using the .forma-field label/description structure.

Authoring tag
<forma-text-field>
Category
Form inputs
Behavior owner
Native HTML
Canonical source
patterns/text-field.html

Purpose

A text field collects a short, single-line value. Forma supplies the .forma-field structure (a grid of label, description and control) and the foundation styling for native inputs; the input element itself stays native, so the browser owns typing, autofill, input modes, constraint validation and form submission. The same .forma-field structure is shared by Textarea and Date and time field, and this entry documents it.

Use when

  • The answer is a short free-form value such as a name, email address, URL, phone number or identifier.
  • The value has a native input type (email, password, url, tel, number) whose keyboard, autofill or validation helps the user.
  • A label and an optional line of guidance should sit above the control in a consistent vertical rhythm.

Avoid when

  • The value is several sentences or lines: use Textarea.
  • The value is a date or time: use Date and time field so the platform picker and typed entry stay available.
  • The user chooses from a known list: use Select, Choice group or, for long lists with typing, Combobox.
  • The value is a bounded count the user adjusts in small increments: use Numeric stepper.
  • The field is a query that filters results: use Search, which adds the search landmark, clearing and result-count feedback.

Behavior to know

  • Label, description and control stack in a single grid column with a fixed 0.5rem gap.
  • Native inputs fill the available inline size and keep a 2.75rem (44px) minimum block size.
  • The label is a real label element tied to the input with for/id; the description is linked with aria-describedby.

Basic example

The smallest correct markup: the canonical pattern from patterns/text-field.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal text field

Rendered from the canonical pattern file.

We send sign-in links to this address.
HTML · Minimal text field Raw HTML for HTML · Minimal text field
<forma-text-field class="forma-component-tag">
<div class="forma-field">
  <label class="forma-field__label" for="text-field-email">Work email</label>
  <span class="forma-field__description" id="text-field-email-description">We send sign-in links to this address.</span>
  <input id="text-field-email" name="email" type="email" autocomplete="email" aria-describedby="text-field-email-description" required>
</div>
</forma-text-field>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Sign-in credentials

Email and password fields with the autocomplete tokens password managers rely on. The password description states the rule up front instead of waiting for an error.

Static specimen. Submitting or resetting it needs the consuming application's form handling, which this documentation does not have. Its controls are shown for their markup and appearance and cannot be operated here.

At least 12 characters.
HTML · Sign-in credentials Raw HTML for HTML · Sign-in credentials
<forma-text-field class="forma-component-tag">
  <form class="forma-stack" action="/sign-in" method="post">
    <div class="forma-field">
      <label class="forma-field__label" for="text-field-sign-in-email">Email address</label>
      <input id="text-field-sign-in-email" name="email" type="email" autocomplete="username" spellcheck="false" required>
    </div>
    <div class="forma-field">
      <label class="forma-field__label" for="text-field-sign-in-password">Password</label>
      <span class="forma-field__description" id="text-field-sign-in-password-description">At least 12 characters.</span>
      <input id="text-field-sign-in-password" name="password" type="password" autocomplete="current-password" minlength="12" required aria-describedby="text-field-sign-in-password-description">
    </div>
    <button type="submit">Sign in</button>
  </form>
</forma-text-field>

Click or tap the code once to select all of it, then copy.

Scenario

Validation error

A URL field after the application rejected the value. aria-invalid marks the input and a validation message is linked through aria-describedby together with the original guidance, so the error is announced and visible with a non-color mark.

Must start with https:// and be reachable from our servers.

Use an https:// address. Plain http is not accepted for webhooks.

HTML · Validation error Raw HTML for HTML · Validation error
<forma-text-field class="forma-component-tag">
  <div class="forma-field">
    <label class="forma-field__label" for="text-field-validation-error-webhook">Webhook URL</label>
    <span class="forma-field__description" id="text-field-validation-error-webhook-description">Must start with https:// and be reachable from our servers.</span>
    <input id="text-field-validation-error-webhook" name="webhook" type="url" inputmode="url" value="http://hooks.internal/deploy" aria-invalid="true" aria-describedby="text-field-validation-error-webhook-description text-field-validation-error-webhook-error">
    <p class="forma-validation-message" id="text-field-validation-error-webhook-error">
      <span class="forma-validation-message__mark" aria-hidden="true">!</span>
      Use an https:// address. Plain http is not accepted for webhooks.
    </p>
  </div>
</forma-text-field>

Click or tap the code once to select all of it, then copy.

Scenario

Read-only and disabled values

A generated identifier the user may select and copy (readonly: focusable and submitted) beside a field that does not apply to the current plan (disabled: skipped by focus and not submitted). Each description explains why the value cannot be edited.

Generated by the platform. Select the value to copy it.
Available on the Enterprise plan.
HTML · Read-only and disabled values Raw HTML for HTML · Read-only and disabled values
<forma-text-field class="forma-component-tag">
  <div class="forma-stack">
    <div class="forma-field">
      <label class="forma-field__label" for="text-field-read-only-client-id">Client ID</label>
      <span class="forma-field__description" id="text-field-read-only-client-id-description">Generated by the platform. Select the value to copy it.</span>
      <input id="text-field-read-only-client-id" name="client-id" type="text" value="cli_7f3a9c21e84b" readonly spellcheck="false" aria-describedby="text-field-read-only-client-id-description">
    </div>
    <div class="forma-field">
      <label class="forma-field__label" for="text-field-read-only-domain">Custom sign-in domain</label>
      <span class="forma-field__description" id="text-field-read-only-domain-description">Available on the Enterprise plan.</span>
      <input id="text-field-read-only-domain" name="custom-domain" type="text" disabled aria-describedby="text-field-read-only-domain-description">
    </div>
  </div>
</forma-text-field>

Click or tap the code once to select all of it, then copy.

Scenario

Quantity and phone number

Type-specific inputs. The number field uses native min, max and step constraints; the telephone field uses type=tel so phones show a dial pad, with no pattern forced because phone formats vary by country.

1 to 500.
Include the country code.
HTML · Quantity and phone number Raw HTML for HTML · Quantity and phone number
<forma-text-field class="forma-component-tag">
  <div class="forma-form-row">
    <div class="forma-field">
      <label class="forma-field__label" for="text-field-numeric-seats">Seats</label>
      <span class="forma-field__description" id="text-field-numeric-seats-description">1 to 500.</span>
      <input id="text-field-numeric-seats" name="seats" type="number" min="1" max="500" step="1" value="25" aria-describedby="text-field-numeric-seats-description">
    </div>
    <div class="forma-field">
      <label class="forma-field__label" for="text-field-numeric-phone">On-call phone</label>
      <span class="forma-field__description" id="text-field-numeric-phone-description">Include the country code.</span>
      <input id="text-field-numeric-phone" name="on-call-phone" type="tel" autocomplete="tel" aria-describedby="text-field-numeric-phone-description">
    </div>
  </div>
</forma-text-field>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

Mobile contact details

A billing contact form at phone width. Each field is full width, labels and descriptions wrap, and input types choose the right on-screen keyboard.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • Inputs are inline-size: 100% of their column, so fields fill the phone width and never overflow horizontally.
  • Every input keeps a 2.75rem (44px) minimum height, a comfortable touch target.
  • Long labels and descriptions wrap onto several lines above the control; the label-description-control order never changes.
  • type=email and type=tel select the email and dial-pad keyboards; autocomplete tokens let the platform offer saved contact details.
  • Rotating to landscape only widens the fields.
HTML · Mobile contact details Raw HTML for HTML · Mobile contact details
<forma-text-field class="forma-component-tag">
  <div class="forma-stack">
    <div class="forma-field">
      <label class="forma-field__label" for="text-field-mobile-name">Billing contact name</label>
      <input id="text-field-mobile-name" name="billing-name" type="text" autocomplete="name">
    </div>
    <div class="forma-field">
      <label class="forma-field__label" for="text-field-mobile-email">Invoice email address</label>
      <span class="forma-field__description" id="text-field-mobile-email-description">Invoices and payment receipts are sent here, not to your sign-in address.</span>
      <input id="text-field-mobile-email" name="billing-email" type="email" autocomplete="email" aria-describedby="text-field-mobile-email-description">
    </div>
    <div class="forma-field">
      <label class="forma-field__label" for="text-field-mobile-phone">Phone</label>
      <input id="text-field-mobile-phone" name="billing-phone" type="tel" autocomplete="tel">
    </div>
  </div>
</forma-text-field>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
forlabel.forma-field__labelid of the input—Associates the visible label with the input so it becomes the accessible name and clicking the label focuses the field.
typeinputtext | email | password | url | tel | numbertextChooses native validation, on-screen keyboard and autofill behavior. Use date/time types through Date and time field.
nameinputstring—Form field name used on submission.
valueinputstringemptyInitial value; the live value is owned by the browser.
autocompleteinputemail | username | current-password | name | tel | …browser heuristicTells the browser and password managers what the field holds so they can offer saved values.
requiredinputbooleanabsentNative constraint: the form will not submit while the field is empty.
minlengthinputinteger—Native minimum length constraint for text-like types.
mininputnumber—Lower bound for type=number.
maxinputnumber—Upper bound for type=number.
stepinputnumber | any1Allowed increment for type=number; also the amount ArrowUp/ArrowDown change the value.
inputmodeinputurl | numeric | decimal | tel | email | …from typeKeyboard hint for touch devices when the type alone does not select the right keyboard.
spellcheckinputfalsebrowser defaultTurns off spelling marks for identifiers and addresses.
readonlyinputbooleanabsentThe value can be focused, selected and copied, and is submitted, but cannot be edited.
disabledinputbooleanabsentRemoves the field from focus order and from form submission.
aria-describedbyinputid list—Links the .forma-field__description and, when present, a validation message, in reading order.
aria-invalidinputtrueabsentSet by the application when a submitted or checked value is rejected, together with a linked Validation message.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-fieldBlock class—Root grid for one field: label, optional description, control and optional validation message stacked with a 0.5rem gap.
.forma-field__descriptionElement class—Supporting guidance in secondary text color at 0.8125rem; referenced by aria-describedby.
.forma-field__labelElement class—Visible label text (0.9375rem, weight 650). Put it on the label element itself.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves focus to and from the input. Disabled inputs are skipped; read-only inputs are focusable.
ArrowUp / ArrowDownOn type=number, increments or decrements by step within min and max (native behavior).
EnterSubmits the owning form through native implicit submission.
Events
EventDescription
input / change / invalidNative events from the input. Forma adds none; the application listens to these when it validates or saves.

Form behavior

A native input: submits name=value, participates in constraint validation (required, type, min, max, minlength, step), is reset by form reset, and is excluded from submission when disabled.

States

Text field states
StateHow it is expressedPresentation
Defaultno state attributesFunctional border on the primary surface.
Focus:focus-visibleTwo-tone focus ring (gap outline plus ring shadow) from the foundation layer, visible on light and dark surfaces.
Requiredrequired attributeNative constraint only; Forma adds no asterisk, so say "required" or "optional" in the label or description where it matters.
Invalidaria-invalid="true" plus a linked .forma-validation-messageThe validation message carries the visible error with a non-color mark. Forma does not restyle the input border for aria-invalid or :user-invalid.
Read-onlyreadonly attributeBehaves natively (focusable, selectable, submitted). Forma applies no distinct read-only styling, so the description must say the value is not editable.
Disableddisabled attributeSkipped by focus and not submitted. The foundation layer sets explicit input colors, so the browser's dimmed disabled look is not guaranteed; explain the reason in the description.

Accessibility

Forma provides

  • The canonical structure uses a real label with for, so the label is the accessible name and a larger click target.
  • Inputs keep a 44px minimum height and a high-contrast two-tone focus ring.
  • Borders map to CanvasText in forced-colors mode, so field edges stay visible.
  • .forma-validation-message shows errors with a text mark as well as weight, not by color alone.

Your application supplies

  • Give every input a unique id and a visible label; do not use placeholder text as the label.
  • Link descriptions and error messages with aria-describedby, and set aria-invalid="true" only while the error is shown.
  • Write error messages that say how to fix the value, and move focus or summarize errors with Validation summary on submit when several fields fail.
  • Use correct type and autocomplete values so assistive technology, autofill and on-screen keyboards work.
  • Explain why a field is read-only or disabled in its description.

Responsive behavior

  • Inputs are block-level to their field: inline-size: 100% with max-inline-size: 100%, so they follow the container width.
  • The field is a single-column grid; long labels and descriptions wrap (overflow-wrap: anywhere on labels) instead of widening the page.
  • There are no breakpoints. Place fields in Stack for a single column or Form row for side-by-side peer fields that keep their controls level and collapse to one column when narrow.
  • The 44px minimum height is kept at every width.

Motion

  • No animation: text inputs, labels and descriptions do not transition. Focus and validation changes appear immediately.

Usage guidance

Do

  • Keep the order label, description, control, validation message, and keep the description short.
  • Validate on submit or on leaving the field, not on every keystroke, and keep the user's input when showing an error.
  • Use type=password with autocomplete=current-password or new-password so password managers work.

Avoid

  • Placeholder-only labels, which disappear on typing and often fail contrast.
  • Using type=number for identifiers such as account numbers or ZIP codes; use type=text with inputmode=numeric.
  • Relying on the dimmed look of a disabled field to communicate why it is unavailable.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.