Nick Paolini Logo
Contact
Building Accessible Web Components: A Developer's Guide to Inclusive Design

Building Accessible Web Components: A Developer's Guide to Inclusive Design

September 1, 2025
By Nick Paolini
AccessibilityWeb ComponentsReactARIAInclusive DesignWCAGFrontend DevelopmentUX

When I first started building web components, I'll admit it—accessibility was often an afterthought. I'd build beautiful, functional interfaces and then scramble to add ARIA labels and keyboard navigation at the end. But over the years, I've learned that accessibility isn't something you bolt on; it's something you bake in from the very beginning. And honestly? It makes you a better developer.

Building accessible web components isn't just about compliance or checking boxes. It's about creating experiences that work for everyone—whether someone navigates with a keyboard, uses a screen reader, or has cognitive differences that affect how they process information. This guide will walk you through the practical steps to build components that are inclusive by design.

Why Accessibility Matters (Beyond the Legal Stuff)

Before we dive into the technical details, let's talk about why this matters:

  • It's More Common Than You Think: Over 1 billion people worldwide have some form of disability. That's a massive portion of your potential users.
  • It Benefits Everyone: Accessible design patterns often improve usability for all users. Captions help in noisy environments, high contrast helps in bright sunlight, and clear navigation helps when you're in a hurry.
  • It Makes You a Better Developer: Thinking about accessibility forces you to understand HTML semantics, user flows, and edge cases more deeply.
  • It's Good Business: Accessible sites have better SEO, wider reach, and often better conversion rates.

The Foundation: Semantic HTML First

The most important accessibility principle is this: start with semantic HTML. Before you reach for custom components or fancy styling, ask yourself: "Is there a native HTML element that does what I need?"

Example: Building a Button Component

Here's how I approach building an accessible button component in React:

// ❌ Bad: Using a div
const BadButton = ({ onClick, children }) => (
  <div className="button" onClick={onClick}>
    {children}
  </div>
);

// ✅ Good: Starting with semantic HTML
const AccessibleButton = ({ 
  onClick, 
  children, 
  disabled = false,
  type = "button",
  ariaLabel,
  ...props 
}) => (
  <button
    type={type}
    onClick={onClick}
    disabled={disabled}
    aria-label={ariaLabel}
    className="px-4 py-2 rounded-lg bg-primary text-white disabled:opacity-50 focus:ring-2 focus:ring-primary focus:outline-none"
    {...props}
  >
    {children}
  </button>
);

The native <button> element gives us keyboard navigation, screen reader support, and focus management for free. When we start with semantic HTML, we're building on a solid, accessible foundation.

Essential ARIA Patterns for Common Components

Sometimes you need to go beyond native HTML elements. That's where ARIA (Accessible Rich Internet Applications) comes in. Here are some patterns I use constantly:

Dropdown Menu Component

const DropdownMenu = ({ trigger, children }) => {
  const [isOpen, setIsOpen] = useState(false);
  const menuRef = useRef(null);
  const triggerRef = useRef(null);

  return (
    <div className="relative">
      <button
        ref={triggerRef}
        aria-expanded={isOpen}
        aria-haspopup="true"
        onClick={() => setIsOpen(!isOpen)}
        className="px-4 py-2 rounded-lg focus:ring-2"
      >
        {trigger}
      </button>
      
      {isOpen && (
        <ul
          ref={menuRef}
          role="menu"
          aria-labelledby="menu-button"
          className="absolute top-full left-0 bg-white shadow-lg rounded-lg"
        >
          {children}
        </ul>
      )}
    </div>
  );
};

Key accessibility features here:

  • aria-expanded tells screen readers whether the menu is open
  • aria-haspopup indicates that this button opens a menu
  • role="menu" identifies the popup as a menu
  • aria-labelledby connects the menu to its trigger button

Keyboard Navigation: Making Everything Reachable

One of the biggest accessibility mistakes I see is components that work great with a mouse but completely break down with keyboard navigation. Here's how to fix that:

Custom Hook for Keyboard Navigation

const useKeyboardNavigation = (onEscape, onEnter, onArrowKeys) => {
  useEffect(() => {
    const handleKeyDown = (event) => {
      switch (event.key) {
        case 'Escape':
          onEscape?.();
          break;
        case 'Enter':
        case ' ': // Space bar
          event.preventDefault();
          onEnter?.();
          break;
        case 'ArrowDown':
        case 'ArrowUp':
          event.preventDefault();
          onArrowKeys?.(event.key);
          break;
      }
    };

    document.addEventListener('keydown', handleKeyDown);
    return () => document.removeEventListener('keydown', handleKeyDown);
  }, [onEscape, onEnter, onArrowKeys]);
};

This hook handles the most common keyboard interactions you'll need across different components. The key is being consistent—users expect Escape to close modals, Enter/Space to activate buttons, and arrow keys to navigate lists.

Focus Management: Guiding User Attention

Good focus management is like being a thoughtful tour guide—you help users understand where they are and where they can go next. Here's how I handle it:

const Modal = ({ isOpen, onClose, children, title }) => {
  const modalRef = useRef(null);
  const previousFocus = useRef(null);

  useEffect(() => {
    if (isOpen) {
      // Save the currently focused element
      previousFocus.current = document.activeElement;
      
      // Focus the modal
      modalRef.current?.focus();
    } else {
      // Return focus to the previously focused element
      previousFocus.current?.focus();
    }
  }, [isOpen]);

  if (!isOpen) return null;

  return (
    <div
      ref={modalRef}
      role="dialog"
      aria-modal="true"
      aria-labelledby="modal-title"
      tabIndex={-1}
      className="fixed inset-0 bg-black/50 flex items-center justify-center"
      onClick={onClose}
    >
      <div
        className="bg-white p-6 rounded-lg max-w-md w-full"
        onClick={(e) => e.stopPropagation()}
      >
        <h2 id="modal-title" className="text-xl font-semibold mb-4">
          {title}
        </h2>
        {children}
      </div>
    </div>
  );
};

This modal component:

  • Saves the previously focused element before opening
  • Moves focus to the modal when it opens
  • Returns focus to the original element when closed
  • Uses proper ARIA attributes for screen readers

Testing Your Components: Tools and Techniques

Building accessible components is only half the battle—you need to test them. Here are my go-to methods:

Automated Testing

// Using jest-axe for automated accessibility testing
import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

test('Button component should be accessible', async () => {
  const { container } = render(
    <AccessibleButton onClick={() => {}} aria-label="Save document">
      Save
    </AccessibleButton>
  );
  
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

Manual Testing Checklist

  • Keyboard-only navigation: Unplug your mouse and navigate using only Tab, Enter, Escape, and arrow keys
  • Screen reader testing: Use NVDA (Windows), JAWS, or VoiceOver (Mac) to experience your component
  • Color contrast: Use tools like WebAIM's contrast checker to ensure sufficient contrast ratios
  • Zoom testing: Test your components at 200% and 400% zoom levels
  • Focus visibility: Make sure focus indicators are clearly visible

Real-World Example: Accessible Data Table

Let me show you a more complex example—a sortable data table that's fully accessible:

const AccessibleTable = ({ data, columns }) => {
  const [sortConfig, setSortConfig] = useState(null);

  const handleSort = (column) => {
    setSortConfig(prev => ({
      key: column,
      direction: prev?.key === column && prev.direction === 'asc' ? 'desc' : 'asc'
    }));
  };

  return (
    <table role="table" aria-label="User data">
      <thead>
        <tr>
          {columns.map(column => (
            <th
              key={column.key}
              scope="col"
              role="columnheader"
              aria-sort={
                sortConfig?.key === column.key 
                  ? sortConfig.direction 
                  : 'none'
              }
            >
              <button
                onClick={() => handleSort(column.key)}
                className="text-left font-semibold hover:underline focus:outline-none focus:underline"
                aria-label="Sort by [column.label]"
              >
                {column.label}
                {sortConfig?.key === column.key && (
                  <span aria-hidden="true">
                    {sortConfig.direction === 'asc' ? ' ↑' : ' ↓'}
                  </span>
                )}
              </button>
            </th>
          ))}
        </tr>
      </thead>
      <tbody>
        {data.map((row, index) => (
          <tr key={index}>
            {columns.map(column => (
              <td key={column.key}>
                {row[column.key]}
              </td>
            ))}
          </tr>
        ))}
      </tbody>
    </table>
  );
};

This table includes:

  • Proper ARIA roles and labels
  • scope="col" for header association
  • aria-sort to indicate sort state
  • Keyboard-accessible sort buttons
  • Visual indicators with aria-hidden="true" to prevent screen reader duplication

Common Mistakes to Avoid

Here are the accessibility pitfalls I see most often (and have definitely made myself):

  • Over-using ARIA: Don't add role="button" to actual <button> elements. Native semantics win.
  • Missing focus states: Never set outline: none without providing an alternative focus indicator.
  • Inadequate color contrast: Ensure at least 4.5:1 contrast ratio for normal text, 3:1 for large text.
  • Forgetting keyboard users: Every interactive element needs to be reachable and operable via keyboard.
  • Generic link text: "Click here" and "Read more" don't provide enough context for screen reader users.
  • Missing alt text: Every meaningful image needs descriptive alt text. Decorative images should have empty alt attributes.

Making Accessibility Part of Your Process

The key to building accessible components isn't perfection from day one—it's making accessibility a consistent part of your development process. Start with semantic HTML, add ARIA thoughtfully, test early and often, and remember that every small improvement makes the web more inclusive.

When you build with accessibility in mind from the beginning, you create better experiences for everyone. And honestly? Once you get into the rhythm of accessible development, it becomes second nature. Your components will be more robust, your code more semantic, and your users—all of your users—will have a better experience.

Want to dive deeper into accessible design patterns? Let's talk about how accessibility can improve your project's user experience and reach.

Back to Blog