BugWP logo BugWP
Back to Community
Home / Community / Core → Accessibility

How to Add and Customize ARIA Labels in WordPress

14 threads Sep 16, 2025 Core → Accessibility

Content

Ensuring your WordPress website is accessible often involves adding or modifying ARIA (Accessible Rich Internet Applications) attributes like aria-label. These attributes provide critical context to screen reader users, making navigation and interaction possible. A common challenge is that these attributes are often hard-coded by a theme or plugin, leaving users searching for a way to change them without direct access to the source code.

Why You Might Need to Change an ARIA Label

You may find yourself needing to modify an ARIA label for several reasons:

  • The default text is generic, like "Open menu" or "Read more," and you want to provide more specific context.
  • A theme or plugin duplicates content, such as repeating the site title in both an aria-label and visible text, causing a screen reader to announce it twice.
  • You need to ensure that multiple links pointing to the same location, but with different visual text (e.g., a button that says "Go" and a text link that says "Click here"), have a consistent, descriptive label for screen readers to meet WCAG consistent identification criteria.

Common Solutions for Modifying ARIA Labels

Since ARIA attributes are part of the HTML markup, they must be modified either at the source code level or, more commonly, using JavaScript. Here are the most effective approaches.

1. Using Custom JavaScript (The Most Common Method)

If you cannot edit the theme's PHP templates directly, adding a small piece of JavaScript via a plugin like "Custom Code Snippets" or your theme's built-in customizer tool is the most versatile solution. This method targets the element by its class, ID, or other attribute to change its aria-label.

Example: Changing a Mobile Menu Toggle Label
The following vanilla JavaScript code finds an element by its class and sets a new ARIA label. You can add this to your site using a custom HTML widget or a code snippets plugin.

<script>
document.addEventListener('DOMContentLoaded', function() {
    var mobileMenuToggle = document.querySelector('.mobile-menu-toggle');
    if (mobileMenuToggle) {
        mobileMenuToggle.setAttribute('aria-label', 'Toggle mobile menu');
    }
});
</script>

Example: Using jQuery
If your theme already loads jQuery, you can use this simpler syntax.

<script>
jQuery(document).ready(function($) {
    $('.mobile-menu-toggle').attr('aria-label', 'Toggle mobile menu');
});
</script>

2. Contacting Your Theme or Plugin Developer

As seen in multiple threads, a frequent response is that the issue originates in a commercial theme (like Avada or Neve) or plugin. The 'Accessibility' team and community often recommend contacting the vendor directly in these cases. They built the product and are in the best position to either:

  • Tell you which theme file to modify in a child theme.
  • Provide a filter or hook you can use.
  • Fix the issue in a future update.

3. For Core WordPress Issues: Submitting a Trac Ticket

If you identify an accessibility issue within WordPress core itself—such as landmarks without unique roles or pagination that lacks proper labels—the best course of action is to report it on the official WordPress Core Trac system. Be sure to select the 'Accessibility' component when creating your ticket. This allows the WordPress accessibility team to review and address the problem for everyone in a future core update.

Important Considerations and Best Practices

  • Translation: If your site is multilingual, remember that any ARIA labels you add manually via JavaScript will also need to be translated.
  • Testing: Always test changes with a screen reader (like NVDA or VoiceOver) to ensure the new labels work as intended and improve the experience.
  • Specificity: Use the most specific CSS selector possible (e.g., #unique-id instead of .common-class) to avoid accidentally targeting the wrong element on the page.

While modifying ARIA labels can seem technical, the JavaScript method provides a powerful and relatively straightforward way to enhance your site's accessibility without needing to edit core theme files.

Related Support Threads Support