VERIFICATION-0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
We send sign-in links to this address.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
labelelement tied to the input withfor/id; the description is linked witharia-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.
Minimal text field
Rendered from the canonical pattern file.
<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
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.
<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.
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.
<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.
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.
<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.
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.
<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 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.
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.
<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.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
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.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
for | label.forma-field__label | id of the input | — | Associates the visible label with the input so it becomes the accessible name and clicking the label focuses the field. |
type | input | text | email | password | url | tel | number | text | Chooses native validation, on-screen keyboard and autofill behavior. Use date/time types through Date and time field. |
name | input | string | — | Form field name used on submission. |
value | input | string | empty | Initial value; the live value is owned by the browser. |
autocomplete | input | email | username | current-password | name | tel | … | browser heuristic | Tells the browser and password managers what the field holds so they can offer saved values. |
required | input | boolean | absent | Native constraint: the form will not submit while the field is empty. |
minlength | input | integer | — | Native minimum length constraint for text-like types. |
min | input | number | — | Lower bound for type=number. |
max | input | number | — | Upper bound for type=number. |
step | input | number | any | 1 | Allowed increment for type=number; also the amount ArrowUp/ArrowDown change the value. |
inputmode | input | url | numeric | decimal | tel | email | … | from type | Keyboard hint for touch devices when the type alone does not select the right keyboard. |
spellcheck | input | false | browser default | Turns off spelling marks for identifiers and addresses. |
readonly | input | boolean | absent | The value can be focused, selected and copied, and is submitted, but cannot be edited. |
disabled | input | boolean | absent | Removes the field from focus order and from form submission. |
aria-describedby | input | id list | — | Links the .forma-field__description and, when present, a validation message, in reading order. |
aria-invalid | input | true | absent | Set by the application when a submitted or checked value is rejected, together with a linked Validation message. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-field | Block class | — | Root grid for one field: label, optional description, control and optional validation message stacked with a 0.5rem gap. |
.forma-field__description | Element class | — | Supporting guidance in secondary text color at 0.8125rem; referenced by aria-describedby. |
.forma-field__label | Element class | — | Visible label text (0.9375rem, weight 650). Put it on the label element itself. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves focus to and from the input. Disabled inputs are skipped; read-only inputs are focusable. |
| ArrowUp / ArrowDown | On type=number, increments or decrements by step within min and max (native behavior). |
| Enter | Submits the owning form through native implicit submission. |
| Event | Description |
|---|---|
input / change / invalid | Native 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
| State | How it is expressed | Presentation |
|---|---|---|
| Default | no state attributes | Functional border on the primary surface. |
| Focus | :focus-visible | Two-tone focus ring (gap outline plus ring shadow) from the foundation layer, visible on light and dark surfaces. |
| Required | required attribute | Native constraint only; Forma adds no asterisk, so say "required" or "optional" in the label or description where it matters. |
| Invalid | aria-invalid="true" plus a linked .forma-validation-message | The 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-only | readonly attribute | Behaves natively (focusable, selectable, submitted). Forma applies no distinct read-only styling, so the description must say the value is not editable. |
| Disabled | disabled attribute | Skipped 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
labelwithfor, 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-messageshows 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%withmax-inline-size: 100%, so they follow the container width. - The field is a single-column grid; long labels and descriptions wrap (
overflow-wrap: anywhereon 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.