Accessible Form Validation in React: Beyond Basic Error Messages

Building user interfaces in React often means reaching for a component library or rolling custom form primitives. While visual styling and client-side validation logic usually get plenty of attention, accessibility (a11y) is frequently bolted on as an afterthought. A red border and a small piece of italicized text under an input might seem sufficient for sighted users, but to a screen reader user, a broken form validation flow can render an application completely unusable.

In this installment of our accessible UI component series, we are moving past basic error messages. We will explore how to build a robust, accessible form validation pattern in React and TypeScript using aria-describedby, live regions, and programmatic focus management.

The Anatomy of an Inaccessible Form Error

Consider a typical React form setup. When a user submits invalid data, state updates, and a conditional string appears beneath the input:

// The anti-pattern: Visually present, programmatically invisible
function BadForm() {
  const [email, setEmail] = useState('');
  const [error, setError] = useState('');

  const handleSubmit = (e) => {
    e.preventDefault();
    if (!email.includes('@')) {
      setError('Please enter a valid email address.');
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="email">Email</label>
      <input
        id="email"
        type="text"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
      />
      {error && <span className="error-text">{error}</span>}
      <button type="submit">Submit</button>
    </form>
  );
}
}

Why does this fail accessibility standards?

1. No programmatic relationship: The <input> has no idea that the <span> containing the error message belongs to it. Screen readers will read the label and the input value, but completely ignore the error text unless the cursor happens to land directly on it.
2. No submission feedback: When the user clicks “Submit”, the page does not reload, and focus stays on the submit button. A screen reader user has no indication that validation failed or that errors now exist on the page.

Let’s fix this step by step.

1. Connecting Inputs to Errors with aria-describedby

The aria-describedby attribute establishes a programmatic relationship between an interactive element and descriptive text elements. By passing the id of the error message container to the input’s aria-describedby, screen readers will automatically read the error message immediately after announcing the input’s label and type.

import React, { useState, useId } from 'react';

export function AccessibleInput({
  label,
  error,
  id: providedId,
  ...props
}: {
  label: string;
  error?: string;
} & React.InputHTMLAttributes<HTMLInputElement>) {
  const generatedId = useId();
  const id = providedId || generatedId;
  const errorId = `${id}-error`;

  return (
    <div className="form-field">
      <label htmlFor={id}>{label}</label>
      <input
        id={id}
        aria-invalid={Boolean(error)}
        aria-describedby={error ? errorId : undefined}
        {...props}
      />
      {error && (
        <div id={errorId} className="error-message" role="alert">
          {error}
        </div>
      )}
    </div>
  );
}

Key Additions Explained:

• aria-invalid={Boolean(error)}: Signals to assistive technologies whether the current field contains invalid data.
• aria-describedby={error ? errorId : undefined}: Dynamically attaches the error message ID to the input only when an error actually exists.
• role="alert": Instantly treats the error container as a live region, instructing screen readers to interrupt current speech and announce the error as soon as it renders.

2. Managing Focus on Submit

When a form fails validation, sighted users naturally scan the page for red outlines or error text. Screen reader users, however, remain wherever their focus was left—usually stubbornly anchored on the submit button.

To solve this, we need to handle form submission programmatically, catch validation failures, and shift focus to either:

1. The first invalid input, or
2. An error summary heading at the top of the form.

Let’s implement a complete form component that demonstrates focus management using a useRef hook.

import React, { useState, useRef, FormEvent } from 'react';
import { AccessibleInput } from './AccessibleInput';

export function SignupForm() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [errors, setErrors] = useState<{ email?: string; password?: string }>({});

  // Refs to target elements for focus management
  const emailRef = useRef<HTMLInputElement>(null);
  const passwordRef = useRef<HTMLInputElement>(null);
  const errorSummaryRef = useRef<HTMLDivElement>(null);

  const handleSubmit = (e: FormEvent) => {
    e.preventDefault();
    const newErrors: { email?: string; password?: string } = {};

    if (!email) {
      newErrors.email = 'Email address is required.';
    } else if (!email.includes('@')) {
      newErrors.email = 'Please enter a valid email address.';
    }

    if (!password || password.length < 8) {
      newErrors.password = 'Password must be at least 8 characters long.';
    }

    setErrors(newErrors);

    if (Object.keys(newErrors).length > 0) {
      // Strategy: Focus the error summary region so screen readers announce the overall failure
      errorSummaryRef.current?.focus();
    } else {
      // Proceed with API submission
      alert('Form submitted successfully!');
    }
  };

  const hasErrors = Object.keys(errors).length > 0;

  return (
    <form onSubmit={handleSubmit} noValidate>
      {/* Error Summary Banner for Screen Readers */}
      <div
        tabIndex={-1}
        ref={errorSummaryRef}
        className={`error-summary ${hasErrors ? 'visible' : 'sr-only'}`}
        role="region"
        aria-label="Form submission errors"
      >
        {hasErrors && (
          <p tabIndex={-1}>
            There are {Object.keys(errors).length} errors in this form. Please review the fields below.
          </p>
        )}
      </div>

      <AccessibleInput
        label="Email Address"
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        error={errors.email}
        ref={emailRef}
      />

      <AccessibleInput
        label="Password"
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        error={errors.password}
        ref={passwordRef}
      />

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

Pro-Tip on tabIndex={-1}: By default, standard div elements are not focusable via JavaScript .focus(). Adding tabIndex={-1} makes the container programmatically focusable without adding it to the natural keyboard tab order.

3. Real-Time vs. On-Submit Validation and Live Regions

Deciding when to validate is a classic UX debate with major accessibility implications.

• On-Submit Validation: Safer for screen readers because it prevents a barrage of premature error announcements while the user is still typing.
• On-Blur Validation: Validates a field immediately after the user leaves it. This is generally well-tolerated by assistive tech if handled carefully.
• On-Change Validation: Can be extremely disruptive if errors trigger while a user is mid-word (e.g., announcing “Invalid email” while they are still typing the prefix before the @ symbol).

If you must use real-time validation or async checks (like checking if a username is already taken), rely on aria-live regions rather than shifting focus aggressively.

export function AsyncUsernameInput() {
  const [username, setUsername] = useState('');
  const [statusMessage, setStatusMessage] = useState('');

  // Simulated async validation check
  const checkUsername = async (value: string) => {
    if (value.length < 3) return;
    setStatusMessage('Checking username availability...');
    // Simulate API delay
    setTimeout(() => {
      if (value === 'admin') {
        setStatusMessage('Username is already taken.');
      } else {
        setStatusMessage('Username is available.');
      }
    }, 600);
  };

  return (
    <div className="form-field">
      <label htmlFor="username">Username</label>
      <input
        id="username"
        type="text"
        value={username}
        onChange={(e) => {
          setUsername(e.target.value);
          checkUsername(e.target.value);
        }}
      />
      {/* Polite live region waits for the user to finish typing */}
      <div aria-live="polite" aria-atomic="true" className="sr-status">
        {statusMessage}
      </div>
    </div>
  );
}
}

Summary Checklist for Accessible React Forms

When reviewing your form components for WCAG compliance, ensure you hit every item on this checklist:

1. Explicit Associations: Every form control has a visible <label> bound via htmlFor and id.
2. Error Linkage: Error messages are tied to inputs using aria-describedby.
3. State Signaling: Invalid inputs include aria-invalid="true".
4. Focus Redirection: Failed submissions programmatically shift focus to an error summary or the first invalid field.
5. Live Announcements: Dynamic validation states utilize aria-live="polite" or role="alert".

By going beyond basic visual error messages and implementing these ARIA patterns in React, you ensure that your applications are resilient, robust, and genuinely welcoming to users of all abilities.