Skip to main content

How to Get an Element by its aria-label in JavaScript

Selecting elements by their aria-label is a common and important task, especially in testing and when working with accessible applications where visible text might be absent (e.g., an icon button). The most powerful and flexible way to do this is with the querySelector() and querySelectorAll() methods, combined with CSS attribute selectors.

This guide will teach you how to use CSS attribute selectors to find elements based on their aria-label attribute, whether you need an exact match or a partial match.

The Core Method: querySelector with Attribute Selectors​

The querySelector() and querySelectorAll() methods are the modern "Swiss Army knife" of DOM selection. They accept any valid CSS selector string, including the powerful set of attribute selectors.

  • document.querySelector('selector'): Returns the first element that matches the selector.
  • document.querySelectorAll('selector'): Returns a NodeList containing all elements that match the selector.

The key is to use the attribute selector syntax: [attribute-name="value"].

We'll use this structure for our examples.

<button aria-label="Close Dialog">X</button>
<button aria-label="Open Menu">☰</button>
<a href="#" aria-label="Close Dialog">Cancel</a>

Selecting by Exact aria-label Value​

This is the most common use case: you know the exact aria-label text and want to find the corresponding element(s).

For example, we need to find the button with the aria-label of "Close Dialog". How to select the element with aria-label="Close Dialog"?

So, the CSS selector for an exact match is [aria-label="Your Label Text"].

// Get the FIRST element with the exact aria-label
const closeButton = document.querySelector('[aria-label="Close Dialog"]');
console.log(closeButton.tagName);       // Output: "BUTTON"

// Get ALL elements with the exact aria-label
const allCloseElements = document.querySelectorAll('[aria-label="Close Dialog"]');
console.log(allCloseElements.length);   // Output: 2

You can also make the selector more specific by including the tag name:

// Get only the <a> element with this aria-label
const closeLink = document.querySelector('a[aria-label="Close Dialog"]');
console.log(closeLink.textContent);     // Output: "Cancel"

Selecting by Partial aria-label Value​

Attribute selectors also provide powerful options for partial matching, which is very useful for testing or working with dynamic labels.

[aria-label^="value"] - Attribute Starts With​

This finds elements where the aria-label begins with a specific string.

// Get all elements whose aria-label starts with "Close"
const allCloseElements = document.querySelectorAll('[aria-label^="Close"]');
console.log(allCloseElements.length); // Output: 2

[aria-label$="value"] - Attribute Ends With​

This finds elements where the aria-label ends with a specific string.

// Get the element whose aria-label ends with "Menu"
const menuButton = document.querySelector('[aria-label$="Menu"]');
console.log(menuButton.textContent); // Output: "☰"

[aria-label*="value"] - Attribute Contains​

This finds elements where the aria-label contains a specific substring anywhere within it.

// Get all elements whose aria-label contains the word "Dialog"
const dialogElements = document.querySelectorAll('[aria-label*="Dialog"]');
console.log(dialogElements.length); // Output: 2

Conclusion​

Using querySelector and querySelectorAll with CSS attribute selectors is the modern, standard, and most flexible way to find elements by their aria-label.

  • To select by exact value, use [aria-label="value"].
  • To select by partial value, use one of the powerful prefix matchers:
    • ^= for starts with.
    • $= for ends with.
    • *= for contains.

By mastering these simple patterns, you can select any element on the page based on its aria-label with precision and clarity, which is especially important for writing robust and accessible web applications.

Table of Contents