Site Navigation

Reported as: Missing navigation semantics

A site navigation component must be enclosed in a navigation landmark.

When the links sit in a plain <div> or a bare <ul>, nothing identifies them as navigation. Users who move through the page by landmark never find them and have to read from the top of every page to reach them. Nothing separates the links that move users around the site from the links in the content.

Wrap the set in a <nav> element, or give its container role="navigation" when the element can't be changed.

Severity: Serious

Reported as: Nested navigation elements

A site navigation landmark shouldn't contain another navigation landmark, or sit inside one.

When a breadcrumb or a section menu with its own <nav> is rendered inside the site navigation landmark, assistive technology reports the inner landmark as part of the outer one. Users moving by landmark meet the same region twice and can't tell whether they've reached somewhere new.

Keep each navigation landmark separate. Remove the inner landmark, or move the set it wraps out of the site navigation landmark, so each landmark stands for one set of links.

Severity: Moderate

Reported as: Navigation name

When a page has more than one navigation landmark, the site navigation landmark should have a name that tells it apart from the others.

When several landmarks are all reported only as "navigation", screen reader users choosing from a list of landmarks have nothing to choose by. They have to enter each one to find the site navigation landmark.

Name it with aria-labelledby pointing at a visible heading, or with aria-label, using a name like "Main". Leave the word "navigation" out of the name, or screen reader users hear it twice. When the same links appear in a second landmark, such as the footer, give both the same name.

Severity: Minor

Reported as: No group members with required role

A site navigation component must contain elements with the link role.

When the component's items are built from elements with click handlers but no link role, screen reader users enter the landmark and hear text with no way to tell it leads anywhere. They also can't list the site's links, and voice control users can't target them by name.

Make each destination an <a> element with an href, or give a custom element role="link".

Severity: Serious

Reported as: Element has incorrect role

Each part of the site navigation component must expose the role listed above.

When a part doesn't expose its role, assistive technology misreports it. Screen reader users hear a link built from a <span> as plain text, and a disclosure control built from a <div> gives no sign that it can be operated, so users can't tell which items to follow and which to open.

Build the component from native elements: <nav>, <ul> and <li>, <a> with an href, and a <button> or a <summary> for each disclosure control. Add the matching role only when an element can't be native.

Severity: Critical

Reported as: Incorrect root element

The navigation role should sit on the outer element of the site navigation component, the one that holds every link and disclosure control.

When the role sits on an inner part, such as one of the nested lists or a wrapper around some of the links, the landmark covers only that part. Users who jump to the landmark land partway through the component and don't reach the links outside it.

Put the navigation role, or the <nav> element, on the element that contains the whole set, and remove it from the inner parts. If the test selected an inner element by mistake, select the component's <nav> element itself and run the test again.

Reported as: Accessible name

A disclosure control in a site navigation component must have an accessible name that says which section it reveals.

When the control holds only an icon, such as a chevron, or an image with empty alt text, users get a control they can operate and can't identify. Every disclosure control in the component then exposes the same name or none, so finding a section means opening each panel in turn.

Name the control from the text inside it. When the design shows only an icon, give a child image meaningful alt text, or give a button an aria-label or an aria-labelledby pointing at visible text.

Severity: Critical

Reported as: Summary has no accessible name

When a section of a site navigation component is built from a <details> element, its <summary> must have an accessible name that says which section it reveals.

When the <summary> is empty, or holds only an icon or an image with empty alt text and has no aria-label, users get a control they can't identify. Every disclosure control in the component then exposes the same name or none.

Put the section's name inside the <summary>. When the design leaves no visible text to use, give a child image meaningful alt text, or give the <summary> an aria-label.

Severity: Critical

Reported as: Native disclosure is missing summary element

A section of a site navigation component built from a <details> element must have a <summary> element with an accessible name as its first child.

When the first child is the panel's list of links, the browser still renders a control and names it with a default string, usually "Details". Users get a set of identically named controls in the component and no way to tell which section holds the page they want.

Put a <summary> first inside the <details> element and give it the section's name.

Severity: Serious

Reported as: Accessible name

A site navigation link must have an accessible name that identifies the page it leads to.

Without an accessible name, assistive technology can only report that a link is there, so screen reader users can't tell where it goes, and voice control users have no name to speak to follow it. When the link is a home link drawn as a logo, users lose the usual way back to the start of the site.

Give each link visible text naming its page. When a link shows only an icon or a logo, give the image meaningful alt text or give the link an aria-label.

Severity: Serious

Reported as: Disclosure panel has no accessible name

A site navigation panel that carries a role should take its accessible name from the disclosure control that reveals it.

When a panel has a group or region role and no name, assistive technology reports an unnamed group or region. Screen reader users who move into the panel's links can't tell which section of the site they're in.

Give the control an id and point the panel's aria-labelledby at it, so the name can't drift from the control's wording. Give the panel a role only when it needs one.

Severity: Minor

Reported as: Conflicting aria-expanded value

The aria-expanded value of a button that opens a site navigation panel must match whether the panel is showing: false while its links are hidden and true while they're available.

When the value is derived from something other than the panel's real state, it reports the opposite of what's on screen. Screen reader users skip a panel of links that's open in front of them, or go looking for links that were never revealed.

Set the attribute from the same state that decides whether the panel renders.

Severity: Critical

Reported as: Aria-expanded value did not change

The aria-expanded value of a button that opens a site navigation panel must change whenever the panel opens or closes, including when the panel closes because users pressed Escape or moved focus out of the landmark.

When the panel changes and the value doesn't, the attribute goes on reporting the state the panel was in before, so screen reader users are told a section's links are hidden while they're showing, or the reverse.

Change the attribute in the same step that shows or hides the panel, whatever caused it to open or close.

Severity: Serious

Reported as: Missing aria-expanded attribute

A button that opens a site navigation panel must carry aria-expanded, in the collapsed state as well as the expanded one.

When the attribute is absent, nothing in the markup says the button reveals anything, so screen reader users have no reason to expect a panel of links to appear and can't tell afterward whether activating it worked.

Set it to false from the start rather than adding it once the panel has been opened.

Severity: Serious

Reported as: Component does not support disabled state

A disabled state must be declared only on a link or a button in a site navigation component.

When aria-disabled is set on the <nav> element, a list, or a list item, the role has no disabled state to report. ARIA 1.2 deprecated aria-disabled on the navigation role. Assistive technology may ignore the attribute or misreport it, and the links inside stay fully operable, so users can't tell what the design meant to turn off.

Remove the attribute from the container. Disable the individual links or buttons that are unavailable, or leave them out of the component.

Severity: Serious

Reported as: Element type does not support disabled state

An element in a site navigation component must carry disabled or aria-disabled only when its role supports a disabled state.

When the state sits on an element whose role has none, such as a wrapper, a list item or a heading, assistive technology may drop it or report it on something users can't operate, while the control that really is unavailable is still reported as available.

Remove the attribute from that element, and set the disabled state on the control itself, using an element or role that supports it, such as a native <button>.

Severity: Serious

Reported as: Conflicting disabled values

A site navigation link or button must declare its disabled state one way only.

When a native <button> carries disabled alongside aria-disabled="false", or a link carries disabled alongside aria-disabled, the two can disagree, and assistive technology can report a different state from the one the browser enforces. Users can't tell whether the section or the page is available.

Use the disabled attribute on a native <button> and aria-disabled on a button built from a generic element, never both. Disable a link by removing its href, or with role="link" and aria-disabled="true" alone when it has to keep its role.

Severity: Serious

Reported as: Element does not support the disabled attribute

A site navigation link, or a button built from a generic element, must convey its disabled state with aria-disabled rather than disabled.

Browsers ignore the disabled attribute on <a>, <div>, and <span> elements. When a link or button carries it, assistive technology still reports it as available and it still works, however grayed out it looks. Users then try to follow a link or open a panel the design means to be unavailable.

Remove href from a link's <a> element to disable it, adding role="link" and aria-disabled="true" when it has to keep its role. On a generic button, set aria-disabled="true" and block activation in its handlers, or switch to a native <button> and use disabled.

Severity: Serious

Reported as: Unexpected interactives in menu

A site navigation component must hold only links and disclosure buttons.

When another kind of control sits among them, assistive technology presents it in a way the rest of the navigation doesn't match, and keyboard users may not reach or operate it the way they expect.

Keep the navigation to links and disclosure buttons. Move a search field or another control out of the navigation landmark, and give it a landmark of its own when it needs one.

Severity: Minor

Reported as: Menu as a nav element

A site navigation component should be built from links in a navigation landmark rather than with the menu or menubar role.

When the bar is a menubar and its links are menuitem elements, screen reader users are told they've reached a set of commands. They press the arrow keys and nothing happens, or the Tab key skips the whole set. The component also doesn't appear in the page's list of landmarks, where users look for it.

Use a <nav> element holding lists of links and disclosure controls. Keep the menu roles for menus of commands that act on the page.

Severity: Minor

Reported as: Forbidden interactive children; Nested interactive elements

A site navigation link or disclosure control must not contain another interactive element, such as a button or a second link.

When one control is nested inside another, browsers and assistive technologies handle it differently. A disclosure control's children are presentational, so screen reader users can't perceive or follow a link inside one. A disclosure control inside a link gives every click or key press two plausible targets, and users can't tell which one they'll reach.

Take the inner control out and place it beside the other in the list item, as a disclosure control sits beside its section's link.

Severity: Serious

Reported as: Aria-controls has multiple targets

The aria-controls attribute of a button that opens a site navigation panel should name one element, the panel that holds its section's links.

When it lists several ids, the button claims to drive several separate elements, and assistive technology that offers to move users to the controlled content has to pick a target or offer none.

Point aria-controls at the single element that holds the panel. When the panel is made of several elements, wrap them in one container and name that container instead.

Severity: Minor

Reported as: Invalid aria-controls reference

The aria-controls attribute of a button that opens a site navigation panel must name an element that exists on the page.

When the id matches nothing in the document, the reference fails quietly. Assistive technology finds no target, so it can't tell users which panel the button opens, and the markup still looks correct to anyone reading it.

Generate the panel's id and the aria-controls value from one source. When the panel exists only while it's open, add the attribute when the panel appears and remove it when the panel is destroyed.

Severity: Minor

Reported as: Missing aria-controls attribute

A button that opens a site navigation panel should identify the panel with aria-controls.

When the attribute is missing, nothing in the markup states which panel of links the button affects, and assistive technology that uses the relationship has nothing to offer users.

Add aria-controls to the button and set its value to the panel's unique id. Keep the panel right after the button in its list item rather than relying on the attribute to lead users there.

Severity: Minor

Reported as: Avoid aria-owns

A site navigation component should hold its links and panels in the DOM rather than claim them with aria-owns.

When aria-owns pulls a panel of links into the component from elsewhere, those links land after the component's own items in the accessibility tree while focus still follows the DOM. Screen reader users hear a section's links away from its disclosure control, and the Tab key reaches them in a different order.

Assistive technology that doesn't honor the attribute reports the links outside the landmark, so screen reader users get only part of the site's navigation.

Put each panel inside the list item that holds its disclosure control in the DOM, and remove aria-owns. When a framework renders the panels elsewhere, render the whole component there instead.

Reported as: Invalid aria-owns values

When a list in a site navigation component uses aria-owns anyway, each element it references should be a list item.

When the list owns a link, a disclosure control or a panel that isn't a list item, its item count and positions stop matching the navigation, and screen reader users hear a list whose items don't add up.

Put each link and disclosure control in its own list item inside the list in the DOM, and remove aria-owns, as the section intro describes.

Reported as: Keyboard accessible

A site navigation link or disclosure control must be reachable with the Tab key.

When it's built from an element that isn't natively focusable, such as a <span> with a click handler, keyboard users can't reach it, or the pages behind it.

Use an <a> element with an href for a link, and a <button> or a <summary> element for a disclosure control. When a custom element can't be avoided, add tabindex="0" to put it in the tab order, and don't set tabindex to a value greater than 0, which takes it out of the component's order.

Severity: Critical

Reported as: Disabled element focusable

A site navigation link or button that presents as disabled should not be in the tab order.

When a disabled link or button keeps its tab stop, keyboard users moving through the component land on an item they can't use.

Remove href from a disabled link's <a> element, which takes it out of the tab order, and set role="link" and aria-disabled="true" when it has to keep its role. Use the disabled attribute on a native <button>. On a custom link or button, remove tabindex="0" while it's disabled.

If users need to find the item and learn why it's unavailable, it can keep its tab stop: set aria-disabled="true", make sure activating it does nothing, and reference visible text giving the reason with aria-describedby.

Severity: Minor

Reported as: Focusable offset

Focus on a site navigation link or disclosure control must land on the element that carries its role, not on a descendant.

When focus lands on a child of the element with the role, users tabbing through the component aren't told what they've reached, and screen readers may not announce the aria-current state that marks the current page or a button's aria-expanded state.

Use an <a> element with an href, a <button>, or a <summary>. Otherwise, keep tabindex="0" on the element that carries the role, and remove focusability from the descendant that was taking focus.

Severity: Minor

Reported as: Unreachable links

Every link in a site navigation component must be reachable and operable with the keyboard.

When a panel opens only on hover, when its disclosure control can't be focused or doesn't respond to Enter and Space, or when a link has no href, keyboard users can't reach those pages. Voice control users can't target a link that isn't exposed either.

Make each link an <a> element with an href. Make each panel's disclosure control keyboard operable and have it report its state, and hide a closed panel in a way that removes its links from the tab order and restores them when it opens.

Severity: Critical

Reported as: Button not activated by keyboard

A button that opens a site navigation panel must open and close the panel when keyboard users activate it.

When a button built from a generic element handles only the click event, keyboard users can focus it but can't reveal the links in its panel, so they can't reach those pages.

Use a native <button> element, which is keyboard operable on its own. Otherwise, add keyboard event listeners that either toggle the panel or create a click event that does.

Severity: Critical

Reported as: Disabled button keyboard activation

A button that opens a site navigation panel and reports itself as disabled should reject keyboard activation.

When a button carries aria-disabled="true" but Enter or Space still opens its panel, screen reader users are told the section is unavailable and then find it isn't, which may confuse them or undermine their trust in the component.

Use a native <button>, which blocks interaction when disabled is set. Otherwise, check the disabled state in the keyboard handlers and return before toggling anything.

Severity: Serious

Reported as: Button requires space key activation

A button that opens a site navigation panel must activate with Space as well as Enter, as a <button> element does.

When only Enter works, users who press Space, as they would on any other button, may conclude the button is unresponsive and never reach the section's links.

Add a Space keyup handler that toggles the panel, or use a native <button> element.

Severity: Minor

Reported as: Link cannot be activated with keyboard

A site navigation link must go to its page when users press Enter.

When a custom link has only a click handler, keyboard users press Enter on it, get no response, and can't reach that page from the navigation landmark.

Use an <a> element with an href attribute, which follows the link with a pointer or the Enter key with no code, or give a custom link a keydown handler for Enter that runs the same navigation code as its click handler.

Severity: Critical

Reported as: Disabled element active

A site navigation link that presents as disabled must not navigate when it's activated.

When a link carries aria-disabled="true" or is styled to look unavailable but keeps its href or its click and key handlers, users can still activate it and land on a page they were told wasn't available.

Remove href from the link's <a> element to disable it, and set role="link" when it has to keep its role. For a custom link, have the event listeners check the disabled state and return before navigating.

Severity: Moderate

Reported as: Element's state did not change

A button that opens a site navigation panel must update aria-expanded every time it's operated.

Nothing looks broken to sighted users, who watch the panel open and close, while screen reader users are told it's still in the state it started in. After a few presses with no change in what they hear, they decide the button is broken and miss the section's links.

Derive the attribute from the same state that decides whether the panel shows, and handle pointer and keyboard activation through one path rather than two.

Evinced reports this issue as Critical or as Serious, depending on the context where it shows up.

Severity: Critical

Reported as: Toggle state not resetting

When a button that opens a site navigation panel is activated twice, aria-expanded must return to the value it started with.

When the code assigns a fixed value on activation instead of inverting the current one, the attribute stops tracking the panel after the first press. The panel goes on opening and closing, and screen reader users are told a closed panel is open.

Invert the state on each activation rather than assigning a fixed value.

Evinced reports this issue as Critical or as Serious, depending on the context where it shows up.

Severity: Critical

Reported as: Invalid toggle attribute

When a section of a site navigation component is built from a <details> element and carries aria-expanded on the <details> or its <summary> (not recommended), the value must stay consistent with the open attribute.

The browser derives the state from open while assistive technology reports the ARIA value, and nothing updates the attribute when the section opens. Screen reader users are told that a panel of links they've just opened is closed.

Remove aria-expanded and let the native state stand. When it can't be removed yet, update it from the toggle event on the <details> element so it tracks open.

Severity: Serious

Reported as: Disabled element active

A button that opens a site navigation panel and presents as disabled must not open the panel when it's activated.

aria-disabled="true" changes only what's reported, not what the browser allows, so the click and key handlers keep firing unless the code checks the state. Users are told a section isn't available and then find that it opens.

Check the disabled state at the top of the handler and return before changing anything, covering the pointer and keyboard paths. On a native button, use the disabled attribute, which stops activation in the browser.

Severity: Moderate

Reported as: Disclosure is not closed with Escape key

A site navigation panel that opens over other content must close when users press Escape, and focus must return to the disclosure control that opened it.

When there's no handler for Escape, the panel covers what users were reading and the only way out is to find the control again and activate it. When the panel closes but focus stays on a hidden link or drops to the document body, screen reader users hear nothing to say where they are.

Listen for Escape on the control and in the panel, so the key works from either. Close the panel (clear open on a <details> element, or set aria-expanded to false on a button) and call focus() on the control in the same step.

Severity: Serious

Reported as: Deprecated keypress listener

A site navigation component's key handling should use keydown or keyup, not keypress.

When a handler listens for keypress, keys the browser doesn't send through that event go unanswered, and keyboard users find the site navigation component ignoring keys it's meant to respond to.

Replace each keypress listener with a keydown listener, and read the key from event.key.

Severity: Minor

Under 1.3.1 Info and Relationships, site navigation sits in a navigation landmark and holds links, each button that opens a panel carries an aria-expanded value that's present and correct and an aria-controls that references its panel, and a disabled link or button ignores activation.

Under 4.1.2 Name, Role, Value, each part has its correct role, links and disclosure controls have accessible names, the disabled state is declared on a link or button only and one way only, no control holds another, and activating a button updates its state.

Under 2.1.1 Keyboard, every link and disclosure control can be reached with the Tab key and takes focus itself, every link in a panel can be reached, disclosure controls activate with Enter and Space, users follow links with Enter, and an open panel closes with Escape.

The rest are best practices that map to no success criterion: a named landmark kept apart from other landmarks, no menu roles, a panel role named from its disclosure control, a single aria-controls target, and a disabled control that leaves the tab order and ignores the keyboard.

Severity reflects how much an issue gets in users' way. Critical issues leave users unable to identify or reach the site's pages:

• A part without its role
• A disclosure control without a name
• A link or disclosure control that can't be reached or operated by keyboard
• An aria-expanded value that's wrong or doesn't change

Serious issues mislead or strand users:

• Links outside a navigation landmark
• A link without a name
• A missing or stale aria-expanded
• A disabled state reported wrongly
• Nested controls
• A panel that doesn't close with Escape

Moderate issues weaken orientation or trust:

• Nested navigation landmarks
• A disabled link or button that still works

Minor issues cost users some extra effort:

• An unnamed landmark
• Menu roles
• An unnamed panel role
• A missing or broken aria-controls
• A disabled control left in the tab order
• Focus that lands inside a control
• A button that ignores Space

The aria-owns checks and the sanity check on where the navigation role sits carry no severity: Evinced reports them as general and sanity checks.