Text Input

Text Input Variants

Input Types

Size Variants

Experiment with corner rounding using our Border Radius Generator — 6–8px is standard, pill-shaped (9999px) works well for search inputs.

Text Input Properties

Design Token Mappings

See our Design Tokens Complete Guide for a complete token architecture reference.

Text Input States

Focus Ring Best Practices

The focus state is critical — it's the primary indicator for keyboard users. Use a 2px solid ring in a high-contrast color, or combine border color change with a subtle box-shadow:

.text-input:focus-visible {
  border-color: var(--color-primary);
  box-shadow: 0 0 0 3px rgba(var(--color-primary-rgb), 0.15);
  outline: none;
}

Always verify your focus state meets 3:1 contrast against the surrounding background per WCAG 2.1 SC 1.4.11. Use our Contrast Checker.

WCAG Requirements

ARIA Attributes

• aria-required="true" — Marks the field as required. Supplement with a visual indicator (asterisk or "Required" text).
• aria-invalid="true" — Set when validation fails. Screen readers announce "invalid entry".
• aria-describedby="helper-id" — Links helper text or error message to the input. Screen readers announce the description after the label.
• aria-errormessage="error-id" — More specific than aria-describedby for error messages (limited support, use both for now).
• autocomplete — Not an ARIA attribute, but essential for accessibility. Use values from the HTML spec.

Keyboard Interaction

Common Accessibility Mistakes

1. Placeholder as label — Placeholders disappear, leaving the field unlabeled. Always use a <label>.
2. Low-contrast placeholder text — Most browsers render placeholders at ~60% opacity. The resulting contrast often fails WCAG. Adjust with CSS.
3. Red-only error indication — Don't rely on color alone. Add an error icon and text message.
4. Missing autocomplete — Without it, browsers can't autofill and password managers can't detect fields.

For comprehensive form accessibility, see our Accessible Forms Guide and WCAG Practical Guide.

Do's

• ✅ Always use a visible label. Even when space is tight, labels are non-negotiable for accessibility and usability.
• ✅ Use the right type. type="email" gives you free validation, appropriate mobile keyboards, and autocomplete hints. Don't default everything to type="text".
• ✅ Show error messages inline. Place the error directly below the field it relates to. "Please enter a valid email address" is clear. A generic toast saying "Form has errors" is not.
• ✅ Provide autocomplete attributes. They're a huge UX win — users fill forms 30% faster with autocomplete. And they're required by WCAG 2.1 SC 1.3.5.
• ✅ Use inputmode for mobile. inputmode="numeric" shows a number pad on mobile without the downsides of type="number" (spinner arrows, exponential notation, negative values).

Don'ts

• ❌ Don't use type="number" for non-mathematical numbers. Phone numbers, credit cards, ZIP codes, and PINs are not quantities. Use type="text" with inputmode="numeric" and pattern="[0-9]*".
• ❌ Don't validate on every keystroke. It's annoying to see "Invalid email" while you're still typing your email. Validate on blur or on submit. Exception: character counters and format masking can update in real time.
• ❌ Don't disable paste. Ever. Users paste passwords from password managers. Disabling paste is a security AND usability anti-pattern.
• ❌ Don't use placeholder text for important instructions. It disappears. Put guidance in helper text below the field instead.
• ❌ Don't set arbitrary maxLength limits. Some names are long. Some international addresses are long. Only limit length when there's a real technical constraint (e.g., database column limit).

Content Guidelines

• Label: Short, descriptive noun — "Email address", "First name", "Search".
• Placeholder: An example value — "jane@example.com", "e.g., Acme Corp". Not a repeat of the label.
• Helper text: Formatting guidance — "Must be at least 8 characters", "Include country code".
• Error text: Specific and actionable — "Email must include @" not "Invalid input".

Cross-System Comparison

Notable Approaches

Material 3's floating label is the most distinctive text input pattern in modern UI design. The label starts inside the input (like a placeholder) and animates up to a floating position above the field when focused or filled. It's space-efficient and elegant, but has accessibility challenges — some screen readers struggle with the animated label, and it limits the label to short text that fits within the field width.

Ant Design offers the most feature-complete input family. Input.Password includes a built-in show/hide toggle. Input.Search adds a search button with enter-to-submit. Input.TextArea has autoSize that grows vertically as content increases. Input.Group combines multiple inputs into a compound field (e.g., phone area code + number).

Shadcn/ui provides a bare Input component — essentially a styled <input> with Tailwind classes. Labels, helper text, and error states are composed manually using their Label and FormMessage components. This modularity is flexible but requires more assembly per form field.

HTML5 input types deserve emphasis: type="email", type="tel", and type="url" give you free mobile keyboard optimization and basic validation with zero JavaScript. Many custom input implementations ironically ship JavaScript to replicate behavior that native HTML provides for free.

The inputmode attribute is an underused gem. inputmode="numeric" shows a number-only keyboard on mobile without the quirks of type="number" (spinner arrows, exponential notation, empty-on-invalid behavior). Use it for phone numbers, credit cards, PINs, and ZIP codes.