Text input

Problem Context

• The answer is short, user-authored, and not reliably predictable as a fixed option.
• The field may be required, optional, readonly, disabled, or returned from the server with a validation error.
• Users may rely on keyboard, screen reader, browser autofill, paste, mobile keyboards, and zoomed layouts.

Selection Rules

• Choose text input when the user enters a short freeform value such as a reference, title, identifier, one-line note, or organization name.
• Prefer textarea when line breaks, paragraphs, or long-form review are expected.
• Prefer autocomplete when the typed value should resolve to one known record or constrained option.
• Prefer select or radio group when the valid answer is a finite predetermined choice.
• Use specialized inputs when format-specific behavior matters, such as email, password, phone, date, numeric code, payment card, input mask, prefix, or suffix.
• Show a persistent label; do not rely on placeholder text to communicate the question or required format.
• Match input width to the expected answer length and avoid using field width as decoration.
• Validate after blur or submit, preserve typed content, and associate hint and error text with the input.

Required States

• Empty untouched state with persistent label and optional hint.
• Focused state with visible focus indicator.
• Filled valid state showing the typed value exactly as entered.
• Required missing-value error state after attempted submit.
• Invalid format or too-long state with actionable error text.
• Disabled state when the value cannot be changed.
• Readonly state when the value is shown but not editable.
• Autofilled or pasted-value state that remains reviewable before submit.

Interaction Contract

• Typing, deleting, selection, undo, and paste operate like a native single-line text field.
• The visible label remains available before, during, and after text entry.
• Hint and error text are associated through descriptive relationships when present.
• Submitting a required blank field moves the user to a fixable error without clearing other entered values.
• Changing the value after an error updates status without hiding the label or moving focus unexpectedly.
• Browser autocomplete, autocapitalize, spellcheck, and inputmode are configured only when they match the field purpose.

Implementation Checklist

• Use a native input element with a stable id, name, and label element before building a custom field.
• Add hint text near the field and include both hint and error IDs in aria-describedby when they exist.
• Choose type, autocomplete, inputmode, autocapitalize, spellcheck, maxlength, and width based on the specific data being requested.
• Implement required and format validation after interaction or attempted submit, not on initial render.
• Preserve the user's entered value across client validation, server validation, navigation back, and failed submission.
• Test keyboard focus, screen reader label announcement, zoom, mobile orientation, paste, undo, autofill, disabled, readonly, and forced-colors modes.
• Avoid silent trimming, casing, masking, or truncation unless the transformation is previewed and reversible.

Common Generated-UI Mistakes

• Using placeholder text as the only label or instruction.
• Using one single-line field for paragraph answers that need textarea behavior.
• Using text input for predetermined choices that should be select, radio, or autocomplete.
• Showing validation before the user interacts with the field.
• Clearing a user's typed value after an error.
• Silently truncating pasted content.
• Using an input width that implies the wrong answer length.
• Marking a disabled field as the only path to completing the task without explaining why it is locked.

Critique Questions

• Is the answer genuinely short and freeform, or is it a known choice, long answer, or specialized format?
• Does the label remain visible after typing and is the accessible name the same question users see?
• Does the width imply the right answer length?
• When and how does validation appear, and does it preserve the user's value?
• Can users paste, undo, autofill, and return from errors without losing data?