Chrome Extension Accessibility — Best Practices

16 min read

Accessibility in Chrome Extensions

Overview

Extension UIs — popups, options pages, side panels, and injected content — must be accessible to all users. This guide covers ARIA patterns, keyboard navigation, focus management, screen reader support, and high-contrast mode for Chrome extension interfaces.

Why Accessibility Matters for Extensions

Extensions modify the browser experience. An inaccessible extension doesn’t just fail one user — it can break the accessibility of every page it touches. Content scripts that inject UI elements can destroy the accessibility tree of the host page if done carelessly.

Popups are small, focused UIs. Structure them with proper landmarks and headings:

<!-- popup.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <link rel="stylesheet" href="popup.css" />
</head>
<body>
  <main role="main" aria-label="Extension controls">
    <h1 id="popup-title">My Extension</h1>

    <section aria-labelledby="settings-heading">
      <h2 id="settings-heading">Settings</h2>

      <!-- Toggle with accessible label -->
      <div class="toggle-row">
        <label for="enable-toggle">Enable feature</label>
        <button
          id="enable-toggle"
          role="switch"
          aria-checked="false"
          aria-describedby="toggle-desc"
        >
          <span class="sr-only">Toggle</span>
        </button>
        <p id="toggle-desc" class="description">
          Activates the extension on all pages
        </p>
      </div>
    </section>

    <!-- Status messages -->
    <div role="status" aria-live="polite" id="status-message"></div>
  </main>

  <script src="popup.js"></script>
</body>
</html>

/* popup.css */

/* Screen reader only — visually hidden but announced */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

/* Focus visible for keyboard users */
:focus-visible {
  outline: 2px solid #4285f4;
  outline-offset: 2px;
}

/* Don't show outline for mouse clicks */
:focus:not(:focus-visible) {
  outline: none;
}

Every interactive element must be reachable and operable via keyboard:

// popup.ts
function setupKeyboardNavigation() {
  const focusableSelector =
    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';

  document.addEventListener("keydown", (e) => {
    // Escape closes the popup
    if (e.key === "Escape") {
      window.close();
      return;
    }

    // Tab trapping within popup (popups are already modal)
    if (e.key === "Tab") {
      const focusable = [
        ...document.querySelectorAll<HTMLElement>(focusableSelector),
      ].filter((el) => !el.hasAttribute("disabled"));

      if (focusable.length === 0) return;

      const first = focusable[0];
      const last = focusable[focusable.length - 1];

      if (e.shiftKey && document.activeElement === first) {
        e.preventDefault();
        last.focus();
      } else if (!e.shiftKey && document.activeElement === last) {
        e.preventDefault();
        first.focus();
      }
    }
  });
}

// Toggle switch keyboard support
function setupToggle(button: HTMLButtonElement) {
  button.addEventListener("click", () => toggleSwitch(button));
  button.addEventListener("keydown", (e) => {
    if (e.key === "Enter" || e.key === " ") {
      e.preventDefault();
      toggleSwitch(button);
    }
  });
}

function toggleSwitch(button: HTMLButtonElement) {
  const checked = button.getAttribute("aria-checked") === "true";
  button.setAttribute("aria-checked", String(!checked));
  announceStatus(`Feature ${!checked ? "enabled" : "disabled"}`);
}

function announceStatus(message: string) {
  const status = document.getElementById("status-message")!;
  status.textContent = message;
}

Pattern 3: Accessible Content Script Injection

When injecting UI into web pages, preserve the host page’s accessibility:

// content.ts — Accessible injected panel
function createAccessiblePanel(): HTMLElement {
  const host = document.createElement("div");
  host.id = "my-ext-root";

  // Use Shadow DOM to isolate styles without breaking page a11y
  const shadow = host.attachShadow({ mode: "closed" });

  shadow.innerHTML = `
    <style>
      :host {
        all: initial;
        position: fixed;
        top: 16px;
        right: 16px;
        z-index: 2147483647;
      }

      .panel {
        background: white;
        border: 1px solid #ccc;
        border-radius: 8px;
        padding: 16px;
        max-width: 320px;
        box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
        font-family: system-ui, sans-serif;
        color: #333;
      }

      .panel:focus-within {
        outline: 2px solid #4285f4;
      }

      /* High contrast mode support */
      @media (forced-colors: active) {
        .panel {
          border: 2px solid ButtonText;
        }
        button {
          border: 1px solid ButtonText;
        }
      }
    </style>

    <div class="panel"
         role="dialog"
         aria-label="My Extension"
         aria-modal="false">
      <h2 id="panel-title">Extension Panel</h2>
      <div id="panel-content" aria-labelledby="panel-title">
        <!-- Content goes here -->
      </div>
      <button id="close-btn" aria-label="Close extension panel">Close</button>
    </div>
  `;

  // Focus management
  const panel = shadow.querySelector<HTMLElement>(".panel")!;
  const closeBtn = shadow.querySelector<HTMLButtonElement>("#close-btn")!;

  closeBtn.addEventListener("click", () => host.remove());

  // Let Escape close the panel
  shadow.addEventListener("keydown", (e) => {
    if (e.key === "Escape") {
      host.remove();
      // Return focus to the element that triggered the panel
      document.body.focus();
    }
  });

  return host;
}

Pattern 4: ARIA Live Regions for Dynamic Updates

Extensions often update UI dynamically. Use live regions so screen readers announce changes:

// Live region manager
class LiveAnnouncer {
  private container: HTMLElement;

  constructor() {
    this.container = document.createElement("div");
    this.container.setAttribute("aria-live", "polite");
    this.container.setAttribute("aria-atomic", "true");
    this.container.className = "sr-only";
    document.body.appendChild(this.container);
  }

  announce(message: string, priority: "polite" | "assertive" = "polite") {
    this.container.setAttribute("aria-live", priority);
    // Clear then set to ensure re-announcement
    this.container.textContent = "";
    requestAnimationFrame(() => {
      this.container.textContent = message;
    });
  }

  announceUrgent(message: string) {
    this.announce(message, "assertive");
  }
}

const announcer = new LiveAnnouncer();

// Usage examples
announcer.announce("Settings saved");
announcer.announceUrgent("Error: Permission denied");
announcer.announce("3 results found");

Pattern 5: High Contrast and Forced Colors

Support Windows High Contrast Mode and prefers-contrast:

/* Base extension styles */
.badge {
  background: #4285f4;
  color: white;
  border-radius: 4px;
  padding: 2px 8px;
}

.icon-button {
  background: none;
  border: none;
  cursor: pointer;
  padding: 8px;
}

/* High contrast: forced-colors replaces all colors with system colors */
@media (forced-colors: active) {
  .badge {
    /* System colors adapt to the user's chosen contrast theme */
    background: Highlight;
    color: HighlightText;
    /* Borders become critical for visibility */
    border: 1px solid ButtonText;
  }

  .icon-button {
    /* Add visible borders when background colors are gone */
    border: 1px solid ButtonText;
  }

  /* Ensure custom icons remain visible */
  .icon-button svg {
    forced-color-adjust: auto;
  }

  /* Prevent system from overriding specific decorative elements */
  .decorative-gradient {
    forced-color-adjust: none;
  }
}

/* Increased contrast preference */
@media (prefers-contrast: more) {
  :root {
    --border-color: #000;
    --text-secondary: #333; /* darker than usual secondary */
  }

  .subtle-text {
    color: var(--text-secondary);
  }
}

/* Reduced motion */
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.001ms !important;
    transition-duration: 0.001ms !important;
  }
}

Pattern 6: Accessible Options Page

Options pages are full HTML pages with more complex forms:

// options.ts
function setupAccessibleForm() {
  const form = document.querySelector<HTMLFormElement>("#settings-form")!;

  // Group related fields with fieldset/legend
  // <fieldset>
  //   <legend>Notification Settings</legend>
  //   ...fields...
  // </fieldset>

  // Validate and announce errors
  form.addEventListener("submit", (e) => {
    e.preventDefault();
    const errors = validateForm(form);

    // Clear previous errors
    form.querySelectorAll(".error-message").forEach((el) => el.remove());
    form.querySelectorAll("[aria-invalid]").forEach((el) => {
      el.removeAttribute("aria-invalid");
      el.removeAttribute("aria-errormessage");
    });

    if (errors.length > 0) {
      errors.forEach(({ fieldId, message }) => {
        const field = document.getElementById(fieldId)!;
        const errorId = `${fieldId}-error`;

        // Mark field as invalid
        field.setAttribute("aria-invalid", "true");
        field.setAttribute("aria-errormessage", errorId);

        // Insert error message
        const errorEl = document.createElement("p");
        errorEl.id = errorId;
        errorEl.className = "error-message";
        errorEl.setAttribute("role", "alert");
        errorEl.textContent = message;
        field.parentElement!.appendChild(errorEl);
      });

      // Focus the first invalid field
      const firstInvalid = form.querySelector<HTMLElement>("[aria-invalid]");
      firstInvalid?.focus();
    } else {
      saveSettings(form);
      announcer.announce("Settings saved successfully");
    }
  });
}

interface FieldError {
  fieldId: string;
  message: string;
}

function validateForm(form: HTMLFormElement): FieldError[] {
  const errors: FieldError[] = [];
  const apiKey = form.querySelector<HTMLInputElement>("#api-key");

  if (apiKey && !apiKey.value.trim()) {
    errors.push({ fieldId: "api-key", message: "API key is required" });
  }

  return errors;
}

Pattern 7: Extension Keyboard Shortcuts

{
  "commands": {
    "_execute_action": {
      "suggested_key": {
        "default": "Ctrl+Shift+Y",
        "mac": "Command+Shift+Y"
      },
      "description": "Open extension popup"
    },
    "toggle-feature": {
      "suggested_key": {
        "default": "Alt+Shift+T"
      },
      "description": "Toggle the main feature on or off"
    }
  }
}

// background.ts
chrome.commands.onCommand.addListener((command) => {
  if (command === "toggle-feature") {
    // Toggle logic
  }
});

Users can customize these at chrome://extensions/shortcuts — always provide meaningful descriptions.

Pattern 8: Color and Contrast Requirements

Ensure sufficient contrast ratios (WCAG 2.1 AA):

// a11y/contrast.ts
function getLuminance(r: number, g: number, b: number): number {
  const [rs, gs, bs] = [r, g, b].map((c) => {
    c = c / 255;
    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
  });
  return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
}

function getContrastRatio(l1: number, l2: number): number {
  const lighter = Math.max(l1, l2);
  const darker = Math.min(l1, l2);
  return (lighter + 0.05) / (darker + 0.05);
}

// Minimum ratios (WCAG 2.1 AA)
// Normal text: 4.5:1
// Large text (18px+ or 14px+ bold): 3:1
// UI components and graphical objects: 3:1

Testing Accessibility

Chrome DevTools Audit

// In the extension's popup or options page console:
// 1. Open DevTools (right-click > Inspect)
// 2. Lighthouse > Accessibility audit
// 3. Elements > Accessibility pane for ARIA tree inspection

Automated Testing

// tests/a11y.test.ts
import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";

test("popup has no accessibility violations", async ({ page }) => {
  // Load the popup page directly
  const popupUrl = `chrome-extension://${extensionId}/popup.html`;
  await page.goto(popupUrl);

  const results = await new AxeBuilder({ page }).analyze();

  expect(results.violations).toEqual([]);
});

Manual Checklist

All interactive elements reachable via Tab
All actions possible via keyboard alone
Focus order follows visual order
Focus is visible on all interactive elements
Screen reader announces all state changes
Color is not the only means of conveying information
Text meets 4.5:1 contrast ratio (AA)
UI works with 200% browser zoom
Extension works with Windows High Contrast Mode

Summary

Pattern	Key Takeaway
Popup structure	Use landmarks, headings, and `aria-label`
Keyboard navigation	Tab trapping, Escape to close, Enter/Space for actions
Content script injection	Shadow DOM + `role="dialog"` + focus management
Live regions	`aria-live` for dynamic content updates
High contrast	`forced-colors` media query + system colors
Options page forms	`aria-invalid` + `aria-errormessage` + focus first error
Keyboard shortcuts	Commands API with descriptive labels
Color contrast	WCAG 2.1 AA minimums: 4.5:1 text, 3:1 UI

Accessibility is not an afterthought. Build it into your extension from the start, test with real assistive technology, and respect user preferences for contrast, motion, and color schemes. -e —

Part of the Chrome Extension Guide by theluckystrike. Built at zovo.one.

← Previous wxt-framework-setup Next → advanced-i18n