Fixing Navigation That AI Agents Cannot Follow

How an agent sees your menu

A browser-driving agent gets two views of the page. One is a screenshot. The other is the accessibility tree, a simplified outline the browser builds for assistive technology, listing each landmark, heading, link, button and form field with its role and name. When the agent decides what to click, the tree is what tells it that a thing is a link called "Boiler servicing" or a button called "Open Services menu".

Agents that fetch HTML without running scripts see even less. They get the links that are in the HTML as <a href> elements, and nothing else. A menu built after load, or items that only exist when a script runs on hover, simply are not there for them.

That gives three questions to ask of every navigation element:

1. Is it the right kind of element? Going somewhere is a link. Doing something on this page, such as opening a menu, is a button.
2. Does it have a name? The name comes from the element's text, an aria-label, or the alt text of an image inside it. An icon with no text has no name.
3. Can it be reached without a mouse? If it only appears on hover or only responds to a mouse click, an agent may never find or trigger it.

Patterns that stop agents, and what to use instead

Links versus buttons

The single most useful rule: if clicking it changes the address, use a link; if it changes something on the current page, use a button. Agents treat the two differently. A link tells them where they will end up before they click, which lets them plan. A button tells them they will stay on the page and something will change.

<!-- The agent sees a generic element with no destination -->
<div class="nav-item" data-go="/services/">Services</div>

<!-- The agent sees a link called Services that goes to /services/ -->
<a href="/services/">Services</a>

If your site uses a JavaScript framework, its link component usually renders a real anchor already. The problem appears when a developer attaches a click listener to a list item or a card instead. Moving the listener to a proper link, or removing it and letting the link work normally, fixes it. Single-page app routing has its own set of issues, covered in the single-page apps guide.

Drop-downs and mega menus that work for agents

The pattern that works for people, keyboard users, screen readers and agents alike is the disclosure navigation: each top-level item that has children gets a button that shows and hides a list of real links. The button says whether the list is open with aria-expanded. The children are in the HTML from the start.

<nav aria-label="Main">
  <ul>
    <li><a href="/">Home</a></li>
    <li>
      <a href="/services/">Services</a>
      <button type="button" aria-expanded="false" aria-controls="menu-services">
        <span class="visually-hidden">Show Services menu</span>
      </button>
      <ul id="menu-services" hidden>
        <li><a href="/services/boiler-servicing/">Boiler servicing</a></li>
        <li><a href="/services/boiler-repairs/">Boiler repairs</a></li>
        <li><a href="/services/new-boilers/">New boilers</a></li>
      </ul>
    </li>
    <li><a href="/contact/">Contact</a></li>
  </ul>
</nav>

The script behind it only needs to do three things: when the button is clicked, flip aria-expanded between true and false and toggle the hidden attribute on the list; close the list when Escape is pressed; and close it when focus moves elsewhere.

document.querySelectorAll('nav button[aria-controls]').forEach(function (btn) {
  var list = document.getElementById(btn.getAttribute('aria-controls'));
  btn.addEventListener('click', function () {
    var open = btn.getAttribute('aria-expanded') === 'true';
    btn.setAttribute('aria-expanded', String(!open));
    list.hidden = open;
  });
  list.addEventListener('keydown', function (e) {
    if (e.key === 'Escape') { btn.setAttribute('aria-expanded', 'false'); list.hidden = true; btn.focus(); }
  });
});

You can keep opening on hover as well, for mouse users who expect it. What matters is that hover is an extra, not the only way in. Notice too that "Services" stays a link to its own page. That gives the agent a route even if it never opens the menu.

Mega menus

Large menus with columns, images and promotions follow the same rules. Use headings inside the panel for each column, keep every destination a real link, give promotional images alt text that names what they link to, and do not put the only link to an important section inside an image. If the mega menu is heavy, consider a simpler menu with a link to each section's landing page, and let the landing page do the detailed work.

Icons, hamburgers and repeated links

Header icons are the most common unnamed controls. A magnifying glass, a person outline, a bag and three horizontal lines are obvious to most people and meaningless in the accessibility tree unless they carry a name.

<!-- No name: the agent sees "link" or "button" and nothing more -->
<a href="/basket/"><svg>...</svg></a>

<!-- Named, including the count -->
<a href="/basket/"><svg aria-hidden="true" focusable="false">...</svg>
  <span class="visually-hidden">Basket, 2 items</span></a>

<!-- The mobile menu toggle is a button, not a link -->
<button type="button" aria-expanded="false" aria-controls="mobile-nav">
  <svg aria-hidden="true" focusable="false">...</svg>
  <span class="visually-hidden">Menu</span>
</button>

The visually-hidden class is a standard CSS pattern that hides text from sight while leaving it in the accessibility tree. Do not use display: none for this, as that hides the text from agents and screen readers too.

Many sites show a different menu on small screens. Some agents browse with a narrow window, so the mobile menu needs the same care as the desktop one: a named toggle button, aria-expanded, and real links inside. Check it at a narrow width as well as a wide one.

Link text

A page with ten links called "Read more" forces an agent to work out which is which from their position. Name the destination: "Read more about boiler servicing", or make the card's heading the link. If the design must keep short text, add the rest as visually hidden text inside the link.

The fix, step by step

Breadcrumbs, pagination and footers

Breadcrumbs

Breadcrumbs give an agent a map of where it is and a quick way back up. A simple, correct pattern:

<nav aria-label="Breadcrumb">
  <ol>
    <li><a href="/">Home</a></li>
    <li><a href="/services/">Services</a></li>
    <li><a href="/services/boiler-repairs/" aria-current="page">Boiler repairs</a></li>
  </ol>
</nav>

Adding BreadcrumbList structured data that matches the visible trail is useful for search engines and some AI tools, but the visible links are what a browsing agent follows.

Pagination and infinite scroll

Infinite scroll suits casual browsing and is hard for agents. A browser-driving agent has to keep scrolling and has no reliable way to know when it has seen everything; a fetching agent only ever sees the first batch. Numbered pages with real addresses solve both. If you want to keep the scrolling feel, use a Load more button that fetches the next page and also updates the address, and keep page links in the HTML as a fallback.

Footers and landmarks

Label each nav element when there is more than one, for example Main, Breadcrumb and Footer, so an agent can tell them apart. The footer is a good place for links to contact, delivery, returns and opening hours, which are exactly the pages agents are often sent to find. A skip link at the top of the page, pointing at the main content, helps keyboard users and costs nothing.

Edge cases

• Tabs and accordions on a page. These are fine if the tab labels are buttons and the content is in the HTML. If each tab loads its content only when clicked, the agent may never read it. The JavaScript-only content guide covers this.
• Location or language selectors. Use a list of real links to each version of the site rather than a custom drop-down that redirects by script.
• Menus behind a login. Agents usually stop at a login and hand back to the person. Keep public sections public, and do not hide help, pricing or contact pages behind an account.
• Sticky headers that cover content. A tall fixed header can sit on top of the element the agent is trying to click after scrolling. Keep it compact and use scroll-margin-top so linked sections are not hidden beneath it.
• Carousels as navigation. If category links only appear inside a sliding carousel, list them somewhere static as well.