How to make aria labels work?

[royfrancis]

Description

I have been using aria-label in quarto navigation like below as suggested in quarto docs:

_quarto.yml

project: 
  type: website

website:
  navbar:
    left:
      - text: "Home"
        href: "index.qmd"
        aria-label: "Home"

After rendering the page, the menu item looks like this.

  <li class="nav-item">
    <a class="nav-link active" href="./index.html" aria-current="page"> 
<span class="menu-text">Home</span></a>
  </li>  

I was expecting actual aria-label tags but I don't see it. Am I using this incorrectly?

▸ quarto --version
1.10.18

System Version: macOS 26.7.1 (25G241)
      Kernel Version: Darwin 25.6.0

[mcanouil]

You're using it correctly, but aria-label on a navigation item only applies to its icon. Quarto writes it on the <i> element of the Bootstrap icon, and only when the item also has an icon:

• quarto-cli/src/resources/projects/website/templates/navicon.ejs

  Lines 2 to 10 in b74bec2

  	<% if(item.icon) { %>
  	<i
  	class="bi <%- item.icon.startsWith('bi-') ? item.icon : 'bi-' + item.icon %>"
  	role="img"
  	<% if(item["aria-label"]){ %>
  	aria-label="<%- item["aria-label"] %>"
  	<% } %>>
  	</i>
  	<% } %>

For a text-only item like yours, the label is simply ignored. That's fine for accessibility, because the visible text already gives the link its accessible name, and screen readers announce it as "Home, link". You can drop aria-label there.

Where it matters is an icon-only item, which has no visible text to name the link:

website:
  navbar:
    right:
      - icon: github
        href: https://github.com/<user>/<repo>
        aria-label: "GitHub"

This renders <i class="bi bi-github" role="img" aria-label="GitHub">, so screen readers announce "GitHub, link" instead of an unnamed link.

[royfrancis]

Ah! That makes sense. Thanks!

[mcanouil]

The icon markup has some accessibility issues on its own, which are tracked in two issues:

• Navbar item with icon and text renders an unnamed role="img" icon #15123: an item with both icon and text gives its icon role="img" with no name. The icon should be hidden from screen readers instead, and aria-label should name the link rather than the icon. I've added a note there about how the docs describe aria-label.
• a11y: quarto create project blog scaffold has images with no alt text and icon-only navbar links with no name #15038: icon-only links with no aria-label end up with no accessible name, starting with the blog template.

Until those are fixed, a text-only item like yours needs no aria-label, and an icon-only item should always have one.