FeaturesPricingAudit GuideFree StatementDashboard →

Add ARIA Labels to Custom Components

Learn how to use ARIA attributes to label custom components, buttons, and interactive elements. Includes code examples and best practices.

6 min read
serious severityWCAG Level AWCAG 2.1 Success Criterion 1.3.1 and 4.1.2Auto-detectable

What Is It?

ARIA attributes add accessibility information to HTML elements. Key attributes: aria-label (labels element when no visible text), aria-labelledby (links element to labeling text), aria-describedby (provides description).

Affected users: Screen reader users, voice control users, users with visual disabilities, users with cognitive disabilities

Why It Matters

Screen reader users need to understand what each element does. Without ARIA labels, buttons with only icons (like a X close button) are announced as "button" with no context. ARIA bridges this gap.

Good news: Automated tools can detect missing aria-labels on icon buttons, but determining correct label text requires human judgment.

How to Detect This Issue

Test with screen reader. Navigate to elements and check if names/descriptions are announced. Inspect element and look for aria attributes. Use automated accessibility checker.

Automated detection: Run a free SiteArmor scan to automatically detect this issue across your entire website. Check your site →

Code Examples & Fixes

HTML / CSS

Before (inaccessible)
<button>×</button>
After (accessible)
<button aria-label="Close dialog">×</button>

The × symbol is not meaningful to screen readers. aria-label provides context. Alternatively: <button><span aria-hidden="true">×</span> Close</button>

React / Next.js

Before
<button onClick={handleSearch}><SearchIcon /></button>
After
<button onClick={handleSearch} aria-label="Search articles"><SearchIcon /></button>

Icon buttons need aria-label. Alternatively, include text: <button onClick={handleSearch}><SearchIcon /> <span>Search</span></button>

WordPress

Before
<button class="toggle-menu">☰</button>
After
<button class="toggle-menu" aria-label="Toggle navigation menu" aria-expanded="false">☰</button>

Menu toggle buttons should have aria-label and aria-expanded to show menu state. Update aria-expanded="true" when menu opens.

Shopify Liquid

Before
<button class="cart-icon"><i class="icon-cart"></i></button>
After
<button class="cart-icon" aria-label="Shopping cart, 3 items"><i class="icon-cart"></i></button>

Icon buttons in Shopify need aria-labels. For cart buttons, include item count in the label.

Common Mistakes

✗

Using aria-label on elements that already have visible text (redundant)

✗

aria-label text doesn't match visible text (confuses screen reader users)

✗

Forgetting to update aria-expanded when toggles change state

✗

Using aria-label when semantic HTML would be better (use <button> instead of <div>)

✗

aria-hidden="true" used incorrectly, hiding content from screen readers when shouldn't

Frequently Asked Questions

Should I use aria-label or aria-labelledby?
aria-label: when there's no visible text to use. aria-labelledby: when there IS visible text on page that labels the element. Prefer aria-labelledby because it keeps label and element in sync.
Can I use aria-label with visible text?
Don't duplicate. If element has visible text (like <button>Search</button>), don't add aria-label="Search". Screen readers announce both, creating redundancy.
What's the difference between aria-label and title?
title attribute shows on hover for sighted users and is read by screen readers. aria-label is only for screen readers. Use title for helpful hints, aria-label for required accessibility info.
How do I know if I need ARIA?
First: use semantic HTML (<button>, <a>, <fieldset>). If semantic HTML can't express it, then use ARIA. Don't use ARIA when you should use semantic HTML.

Check your website for free

Get your ADA, WCAG, privacy & security score in 90 seconds.

No credit card
WCAG 2.1
ADA
Privacy

Related guides