Text Input

The TextInput component provides a consistent and accessible text entry field with built-in support for validation, helper text, icons, and multiple input types. It uses typography tokens to maintain visual hierarchy across different sizes and states.

API Reference

Props

Usage Examples

Basic Text Input

<script>
  import TextInput from '$lib/shared/components/forms/TextInput.svelte';
  
  let username = $state('');
</script>

<TextInput
  id="username"
  label="Username"
  bind:value={username}
  placeholder="Enter username..."
  helper="Choose a unique username"
/>

With Validation

<script>
  import TextInput from '$lib/shared/components/forms/TextInput.svelte';
  
  let email = $state('');
  let emailError = $state(null);
  
  function validateEmail() {
    if (!email.includes('@')) {
      emailError = 'Please enter a valid email address';
    } else {
      emailError = null;
    }
  }
</script>

<TextInput
  id="email"
  type="email"
  label="Email Address"
  bind:value={email}
  error={emailError}
  onblur={validateEmail}
  required
  icon="mail"
/>

Different Sizes

<!-- Small -->
<TextInput
  id="search"
  type="search"
  label="Quick Search"
  size="sm"
  placeholder="Search..."
  icon="search"
/>

<!-- Large -->
<TextInput
  id="title"
  label="Page Title"
  size="lg"
  placeholder="Enter page title..."
/>

Typography System

The TextInput component uses design system typography tokens to ensure consistent text rendering:

Token Usage by Size

• Small (sm): Uses --typography-caption-* tokens for compact layouts
• Medium (md): Uses --typography-body-* tokens for standard forms (default)
• Large (lg): Uses --typography-heading-* tokens for prominent inputs

Applied Tokens

/* Label */
--typography-caption-size
--typography-caption-color
--typography-caption-weight

/* Input Text */
--typography-body-size    /* md size */
--typography-body-color
--typography-body-weight

/* Helper/Error Text */
--typography-caption-size
--typography-muted-color   /* helper */
--error                    /* error state */

Styling

CSS Classes

The component uses semantic class names that can be customized:

• .field-label - Label element styling
• .field-input - Input field base styles
• .field-error - Error state modifier
• .field-error-message - Error message container
• .field-hint - Helper text styling
• .field-icon - Icon positioning
• .with-icon - Input modifier when icon present

Focus States

Inputs use a dual-layer focus indication:

1. Border color change to --focus-ring
2. Subtle box-shadow for additional visibility

Accessibility

The TextInput component includes comprehensive accessibility features:

• ARIA attributes: aria-required, aria-invalid, aria-describedby
• Label association: Proper for/id linking
• Error announcements: Live regions for screen readers
• Keyboard navigation: Full keyboard support
• Focus management: Clear focus indicators
• Required indicators: Visual asterisk for required fields

Screen Reader Support

• Labels are properly associated with inputs
• Error messages are announced via role="alert"
• Helper text is linked via aria-describedby
• Invalid states communicated via aria-invalid

Best Practices

1. Always provide labels - Every input needs a descriptive label
2. Use appropriate types - Match input type to data (email, tel, url)
3. Provide helper text - Guide users on format or requirements
4. Validate gracefully - Show errors only after user interaction
5. Size appropriately - Use size variants to match visual hierarchy
6. Include icons sparingly - Only when they add clear value

Related Components

• Select - Dropdown selection
• Checkbox - Binary choices
• RadioGroup - Single selection from options
• Toggle - On/off switches