How to give links and buttons an accessible name
Icon-only links and empty buttons are read out as "link" or "button". Add visible text or an aria-label.
Step by step, with screenshots: Touch target size: the 24 px WCAG minimum, the 44-48 px guideline and the exceptions →
Check your own site
Runs this check and the other 192, free, in about 45 seconds.
What it is
An accessible name is the text that assistive technology announces for a link, button or form control, for example "Add to cart, button". Browsers work it out from the element's text, the alt text of an image inside it, or an aria-label or aria-labelledby attribute.
Icon-only links and buttons, such as a cart icon, a magnifier or social media logos, often have no name at all, so a screen reader says just "link" or "button" and the visitor has to guess. Search engines also use link text to understand the page a link points to. getReport lists every link and button without an accessible name. A page is OK when each one has a short name that says where it goes or what it does.
What a passing site looks like
- Every link and button has an accessible namefail · −4 ptseffort S
Link and button names
Why it matters. Icon-only links and buttons are read out as "link" or "button" with nothing else, so screen reader users cannot tell the cart from the search. Search engines also use link text to understand the target page.
- Add visible text, or aria-label="…" on the link or button, that says where it goes or what it does.
- For icon buttons, put the text inside the button and hide it visually with a screen-reader-only class.
Questions people ask
What is aria-label?
It is an HTML attribute that gives an element an accessible name when there is no visible text, such as <button aria-label="Search"> around a magnifier icon. Screen readers read the aria-label instead of the element's content. Use it for icon-only controls, keep it short, and do not add it to elements that already have clear visible text, because it replaces that text.
What is the difference between aria-label and aria-labelledby?
aria-label holds the name as a text string on the element itself. aria-labelledby points to the id of one or more other elements whose visible text becomes the name, such as a heading that labels a section or dialog. aria-labelledby is preferable when the text is already on screen, because the visible and spoken names then always match.
Should I use alt text or aria-label on an image link?
Use alt text. For a link that contains only an image, the image's alt becomes the link's name, so describe the destination: <a href="/"><img src="logo.svg" alt="example-shop home"></a>. An empty alt on the only image in a link leaves the link without a name. Use aria-label for icons drawn with CSS or an icon font instead.