Back to Learn
Pulseaccessibility

Custom Controls Have Associated Labels

What This Audit Checks

This manual audit checks that custom interactive elements (built with <div>, <span>, or Web Components instead of native HTML controls) have an accessible name provided via aria-label, aria-labelledby, or visible associated text.

Why It Matters

Without a label, screen readers announce custom controls as generic elements like "button" or "group" with no description of their purpose. Users cannot determine what a control does without activating it, which is a trial-and-error experience that breaks usability.

How to Fix It

  • Add aria-label for a concise accessible name when no visible text label exists: 
    <div role="button" tabindex="0" aria-label="Close dialog">
  <svg>...</svg>
</div>
  • Use aria-labelledby to reference a visible text element as the label: 
    <h3 id="section-title">Account Settings</h3>
<div role="region" aria-labelledby="section-title">...</div>
  • Prefer native HTML elements whenever possible. A <button> with text content is self-labeling and requires no ARIA.
  • Test with a screen reader. Navigate to each custom control and verify it announces a meaningful name.

How Pulse Tracks This

Pulse flags this audit in your Lighthouse accessibility score. When the audit fails, Pulse shows which elements triggered it so you can fix them directly.

Resources