Skip to content

thedaviddias/Front-End-Checklist / skills/form-validation

form-validation

Verified

Use when reviewing templates, rendered HTML, or shared components related to Validate forms accessibly. Validate the final browser-facing markup, not just the source framework abstraction. Distinguish between browser-posted forms and client-handled React forms so you do not over-report missing `method` or `action` as accessibility defects.

FileKindSize
SKILL.mdskill md2.5 KB
references/rule.mdmarkdown9.0 KB

references/rule.md

View on GitHub
# Validate forms accessibly

> Forms provide clear validation feedback with accessible error messages and proper ARIA attributes.

**Priority:** high · **Difficulty:** intermediate · **Time:** 25 min

---
Accessible form validation ensures all users can understand and correct input errors.

## Code Example

```html
<form novalidate>
  <div class="form-field">
    <label for="email">Email address</label>
    <input
      type="email"
      id="email"
      name="email"
      aria-describedby="email-help email-error"
      aria-invalid="false"
      required
    />
    <span id="email-help" class="form-field__help">
      We'll never share your email
    </span>
    <span id="email-error" class="form-field__error" role="alert" hidden>
      Please enter a valid email address
    </span>
  </div>

  <button type="submit">Subscribe</button>
</form>
```

## Why It Matters

Inaccessible form validation leaves screen reader users unable to understand what went wrong and how to fix it, causing frustration and form abandonment.

## Validation Requirements

| Requirement | Implementation |
|-------------|----------------|
| Required state | `required` or `aria-required="true"` |
| Help text association | `aria-describedby` linking to helper text |
| Error association | `aria-describedby` linking to error |
| Invalid state | `aria-invalid="true"` on field |
| Error visibility | Don't use color alone |
| Focus management | Move focus to first error |
| Error summary | Optional but helpful |

## Grouped Controls

Radio buttons and related checkboxes need a shared semantic label so users hear the question before the options:

```html
<fieldset aria-describedby="contact-help">
  <legend>Preferred contact method</legend>

  <p id="contact-help">Choose the primary way we should contact you.</p>

  <label>
    <input type="radio" name="contact" value="email" required>
    Email
  </label>

  <label>
    <input type="radio" name="contact" value="phone">
    Phone
  </label>
</fieldset>
```

## React Form with Validation

```tsx

interface FormFieldProps {
  label: string
  name: string
  type?: string
  required?: boolean
  error?: string
  help?: string
  value: string
  onChange: (value: string) => void
}

  label,
  name,
  type = 'text',
  required = false,
  error,
  help,
  value,
  onChange
}: FormFieldProps) {
  const inputId = useId()
  const helpId = useId()
  const errorId = useId()

  const describedBy = [
    help ? helpId : null,
    error ? errorId : null,
  ].filter(Boolean).join(' ') || undefined

  return (
    <div className="form-field">
      <label htmlFor={inputId}>
        {label}
        {required && <span aria-hidden="true">*</span>}
      </label>

      <input
        id={inputId}
        name={name}
        type={type}
        value={value}
        onChange={(e) => onChange(e.target.value)}
        aria-describedby={describedBy}
        aria-invalid={!!error}
        aria-required={required}
        className={error ? 'form-field__input--error' : ''}
      />

      {help && (
        <span id={helpId} className="form-field__help">
          {help}
        </span>
      )}

      {error && (
        <span id={errorId} className="form-field__error" role="alert">
          <span className="form-field__error-icon" aria-hidden="true">⚠</span>
          {error}
        </span>
      )}
    </div>
  )
}
```

## Complete Form Example

```tsx
interface FormData {
  name: string
  email: string
  password: string
}

interface FormErrors {
  name?: string
  email?: string
  password?: string
}

  const [formData, setFormData] = useState {
    const newErrors: FormErrors = {}

    if (!formData.name.trim()) {
      newErrors.name = 'Name is required'
    }

    if (!formData.email.trim()) {
      newErrors.email = 'Email is required'
    } else if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(formData.email)) {
      newErrors.email = 'Please enter a valid email address'
    }

    if (!formData.password) {
      newErrors.password = 'Password is required'
    } else if (formData.password.length < 8) {
      newErrors.password = 'Password must be at least 8 characters'
    }

    return newErrors
  }

  const handleSubmit = (e: FormEvent) => {
    e.preventDefault()
    const newErrors = validate()
    setErrors(newErrors)
    setSubmitted(true)

    if (Object.keys(newErrors).length > 0) {
      // Focus first field with error
      const firstErrorField = formRef.current?.querySelector('[aria-invalid="true"]')
      ;(firstErrorField as HTMLElement)?.focus()
      return
    }

    // Submit form
    console.log('Form submitted:', formData)
  }

  const updateField = (field: keyof FormData) => (value: string) => {
    setFormData(prev => ({ ...prev, [field]: value }))
    // Clear error when user starts typing
    if (errors[field]) {
      setErrors(prev => ({ ...prev, [field]: undefined }))
    }
  }

  return (
    <form ref={formRef} onSubmit={handleSubmit} noValidate>
      {/* Error summary (optional but helpful) */}
      {submitted && Object.keys(errors).length > 0 && (
        <div role="alert" className="form-errors" aria-live="assertive">
          <h2>Please correct the following errors:</h2>
          <ul>
            {errors.name && <li><a href="#name">{errors.name}</a></li>}
            {errors.email && <li><a href="#email">{errors.email}</a></li>}
            {errors.password && <li><a href="#password">{errors.password}</a></li>}
          </ul>
        </div>
      )}

      

      

      

      <button type="submit">Create Account</button>
    </form>
  )
}
```

## Real-Time Validation

```tsx
function useValidation(value: string, validators: ((v: string) => string | null)[]) {
  const [error, setError] = useState<string | null>(null)
  const [touched, setTouched] = useState(false)

  const validate = () => {
    for (const validator of validators) {
      const result = validator(value)
      if (result) {
        setError(result)
        return false
      }
    }
    setError(null)
    return true
  }

  const onBlur = () => {
    setTouched(true)
    validate()
  }

  return {
    error: touched ? error : null,
    onBlur,
    validate,
    isValid: !error
  }
}

// Validators
const required = (message: string) => (value: string) =>
  value.trim() ? null : message

const minLength = (min: number, message: string) => (value: string) =>
  value.length >= min ? null : message

const email = (message: string) => (value: string) =>
  /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) ? null : message

// Usage
function EmailInput() {
  const [email, setEmail] = useState('')
  const validation = useValidation(email, [
    required('Email is required'),
    email('Please enter a valid email')
  ])

  return (
     {
        setEmail(v)
        validation.validate()
      }}
      onBlur={validation.onBlur}
      error={validation.error}
    />
  )
}
```

## Styling

```css
.form-field {
  margin-bottom: 1.5rem;
}

.form-field label {
  display: block;
  font-weight: 600;
  margin-bottom: 0.5rem;
}

.form-field input {
  width: 100%;
  padding: 0.75rem;
  border: 2px solid #ccc;
  border-radius: 4px;
  font-size: 1rem;
}

.form-field input:focus {
  outline: none;
  border-color: #0066cc;
  box-shadow: 0 0 0 3px rgba(0, 102, 204, 0.2);
}

.form-field__input--error {
  border-color: #dc3545;
}

.form-field__input--error:focus {
  border-color: #dc3545;
  box-shadow: 0 0 0 3px rgba(220, 53, 69, 0.2);
}

.form-field__help {
  display: block;
  font-size: 0.875rem;
  color: #666;
  margin-top: 0.25rem;
}

.form-field__error {
  display: flex;
  align-items: center;
  gap: 0.25rem;
  font-size: 0.875rem;
  color: #dc3545;
  margin-top: 0.25rem;
}

.form-field__error-icon {
  flex-shrink: 0;
}

/* Error summary */
.form-errors {
  padding: 1rem;
  background: #f8d7da;
  border: 1px solid #f5c6cb;
  border-radius: 4px;
  margin-bottom: 1.5rem;
}

.form-errors h2 {
  font-size: 1rem;
  margin: 0 0 0.5rem;
}

.form-errors ul {
  margin: 0;
  padding-left: 1.25rem;
}

.form-errors a {
  color: #dc3545;
}
```

## Native HTML Validation

```html
<form>
  <label for="email">Email (required)</label>
  <input
    type="email"
    id="email"
    name="email"
    required
    pattern="[^@]+@[^@]+\.[^@]+"
    title="Please enter a valid email address"
  />

  <label for="password">Password (8+ characters)</label>
  <input
    type="password"
    id="password"
    name="password"
    required
    minlength="8"
  />

  <button type="submit">Submit</button>
</form>
```

## Verification

### Automated Checks

- Check focus moves to first invalid field
- Test keyboard-only form completion
- Check errors clear when user corrects input
- Check required fields expose `required` or `aria-required` in rendered markup
- Check each `aria-describedby` reference resolves to visible help or error text

### Manual Checks

- Submit form with empty required fields
- Verify error messages are announced by screen reader
- Verify aria-invalid is set correctly
- Verify error messages are visible without color alone
- Verify grouped controls announce the `<legend>` before the option label
- Verify help text is announced together with the field before and after an error appears
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall