The name behind an icon button

A magnifying glass sits inside a button. Its shape suggests search to many readers. For someone using a screen reader, the button also needs a name that identifies its purpose. The W3C accessible name draft describes that name as a short label drawn from visible text or a text alternative. A screen reader may announce the name with the button’s role. The spoken order varies by platform.

Give the button an action name

This button has no visible words, so aria-label supplies its name:

<button type="button" aria-label="Search">
  <span aria-hidden="true">🔍</span>
</button>

The button’s accessible name is “Search.” The icon is excluded from the name calculation. Someone using a screen reader may hear “Search button.” Naming the action helps them identify the control before activating it.

Use the name in a test

Playwright says its role locators reflect how users and assistive technology perceive a page. It says you typically include the accessible name to target a particular control:

await page.getByRole('button', { name: 'Search' }).click();

The test now targets the button by its role and purpose. If it cannot find “Search,” inspect the name the page exposes. A selector based on position could still click the button without checking that name. Playwright also cautions that role locators do not replace accessibility audits.