Prologue
A while ago, I decided to develop a fully accessible main navigation component in React and write a series of articles documenting the steps it took to create a non-trivial accessible component.
In my last development article, I finally completed keyboard handling for both screen and screen reader users by implementing the last enhancement: sending focus to the top row when entering the component with Shift+Tab.
The foundational support for closing sub-lists when their parent closes was also set up and can now be made use of when closing a list or the component.
Note: This article is one of a series demonstrating building a React navigational component from scratch while considering accessibility through the process. The articles are accompanied by a GitHub repository with releases tied to one or more articles; each builds on the previous one until a fully implemented navigation component is complete.
Each release and its associated tag contain fully runnable code for the article. The code discussed in this article is available in the release. and may be downloaded at release 0.9.0. Links in the article will take you to the proper file in the tagged GitHub Repository.
Because the code for this release is scattered across components, line numbers are added to make it easier to locate in the linked GitHub file. Line numbers are also provided for those who would like to follow along with a downloaded copy.
While code examples are written in JavaScript for brevity, all actual code is written in Typescript and targets React 19.x, all while using vanilla CSS. Examples use Next.js v16.x, which is not required to run the navigation component.
You can view the requirements for the Closings and Exit Release along with previous requirements.
Content Links
Introduction
With keyboard navigation for the desktop menu complete, attention can finally turn to fine-tuning, specifically, the myriad of ways the component needs to handle closing.
When a subnavigation button is toggled, any open children in the list should also close. Open sublists on the top row should close when focus moves to another subnavigation button on the top row. Any open sublists should also close when focus shifts to an element outside the component, regardless of how it happens.
The ARIA Authoring Practices Guide pattern for disclosure navigation explains what happens when closing a component with the Escape key, which, although not detailed, provides a clue about how a component should behave whenever the focus shifts outside the component.
Acceptance Criteria
Closings and Exits Release
- AC 1 - Closing a subnavigation list also closes any open lists nested within.
- AC 2 - When navigating along the top row, any open sublists close when focus shifts.
- AC 3 - When Escape is pressed anywhere in the navigation component, all open sublists close and focus shifts to the topmost parent.
- AC 4 - Any open sublist closes when a pointing device clicks anything outside of the component.
- AC 5 - Any open sublist closes when focus leaves the component.
A plain-English interpretation is that when a parent list closes, any open sublists within it also close. An open sublist on the top row closes when focus shifts along the top row, and all open sublists should close when focus shifts out of the component by any means.
The issues can be observed in this YouTube video.
Closing Sublists on Parent Close
AC 1
- Closing a subnavigation list also closes any open lists nested within.
Closing nested subnavigation lists upon a parent's close meets screen users' expectations. It's a necessary refinement and the first closing to cover.
Nested lists in React mean nested components, and while a Subnavigation component can close its own list, how does it know which nested lists are open, and how can it trigger a close on those lists?
In my previous article, Focus Issues and Refinement Support, I stored each sublist's closeSubNavigation function in a Map object, which is itself held in a ref object. These functions are included in the return value when the getNavigationArray function is called.
SubNavigation
const closeSubNavigation = useCallback(() => {
if (buttonRef.current) {
handleCloseSubNavigation(buttonRef.current);
setIsSubListOpen(false);
}
}, [handleCloseSubNavigation]);
GitHub (release 0.9.0) - useNavigation.tsx - closeSubNavigation() - Line 70
The only component holding the closing information is SubNavigation, so the existing closeSubNavigation function is modified to call a navigation hook function, handleCloseSubNavigation, instead of the setIsListOpen call from the hook.
UseNavigation
const handleCloseSubNavigation = (buttonEl) => {
const dispatchArray = _getElementsInList(buttonEl);
for (const dispatchObj of dispatchArray) {
const { dispatchSubListClose, storedParentEl, isSubListOpen } =
dispatchObj;
if (isSubListOpen && storedParentEl && dispatchSubListClose) {
dispatchSubListClose();
}
}
setIsListOpen(false, buttonEl);
};
GitHub (release 0.9.0) - useNavigation.tsx - handleCloseSubNavigation() - Line 439
The hook function handleCloseSubNavigation creates an array of any button elements in the sublist controlled by the triggering button, then loops through them, running the closeSubNavigation function if the sublist is open. The function triggers a cascade when child sublists have their own open lists.
const _getControllingElementsInList = (parentEl) => {
const controllingListItems = [];
const { storedList } = _getNavigationObjectByParent(parentEl);
storedList.forEach((item) => {
if (item.type === "button") {
const currentObj = _getNavigationObjectByParent(
item as ControllingElementType,
);
controllingListItems.push(currentObj);
}
});
return controllingListItems;
};
GitHub (release 0.9.0) - useNavigation.tsx -_getControllingElementsInList() - Line 68
Within the parent's stored list, any controlling elements (i.e., type="button") retrieve their associated navigation object. This object is then pushed into the array to be returned to the handleCloseSubNavigation function.
With this code in place, any button with an open list will close itself and any open sublists when triggered.
Top Row
Close Open Siblings on Focus
AC 2
- When navigating along the top row, any open sublists close when the parent button loses focus.
The Disclosure Navigation Menu Pattern example of the ARIA Practice Guide demonstrates, but does not document a requirement that open sublists on the top row close when focus shifts. This is once again a refinement that users expect.
It's necessary to use the onFocus event to handle this requirement, regardless of whether the event is triggered on a link or on a button.
SubNavigation
const handleFocus = () => {
handleButtonFocus(buttonRef.current!);
};
GitHub (release 0.9.0) - SubNavigation.tsx - handleButtonFocus () - Line 124
To achieve parity, a handleButtonFocus function is called from the hook, mimicking the handleLinkFocus called from NavigationItem.
useNavigation
const handleButtonFocus = ( buttonEl) => {
if (_isElementInTopRow(buttonEl)) {
_handleTopRowItemFocus(buttonEl);
}
};
const handleLinkFocus = ( linkEl ) => {
if (_isLastElementInComponent(linkEl)) {
...
} else if (_isElementInTopRow(linkEl)) {
_handleTopRowItemFocus(linkEl);
}
};
GitHub (release 0.9.0) - useNavigation.tsx - handleButtonFocus() /handleLinkFocus() - Line 452
Both functions add a call to _handleTopRowItemFocus if and only if the element passed through is in the top row.
const _handleTopRowItemFocus = ( focusedEl ) => {
_closeOpenSiblings(focusedEl);
};
GitHub (release 0.9.0) - useNavigation.tsx - _handleTopRowItemFocus() - Line 187
Since the focused element will always be on the top row, the only call at the moment is to close any open siblings.
const _closeOpenSiblings: UseNavigationInternalTypes["_closeOpenSiblings"] = (focusedEl,) => {
const siblingList = getNavigationArray()[0].storedList;
siblingList.forEach((siblingEl) => {
if (siblingEl !== focusedEl && siblingEl.type === "button") {
const {isSubListOpen, dispatchSubListClose} = _getNavigationObjectByParent(siblingEl);
if (isSubListOpen && dispatchSubListClose) {
dispatchSubListClose();
}
}
});
};
GitHub (release 0.9.0) - useNavigation.tsx - _closeOpenSiblings() - Line 171
The _closeOpenSiblings function retrieves the elements from the top-row list and calls the stored closing function only if the sublist is open and not the list associated with the current button.
The GIF animation demonstrates the result: open sublists close when focus shifts to another button or link on the top row.
Close Component
For the moment, closing a component means making sure all open sublists are closed when interactions leave the component. There are three different scenarios when this happens:
- When the Escape key is pressed while on a focusable element within the component.
- When a pointer event is triggered outside of the component;
- When focus leaves the component.
Close on Escape
AC 3
- When Escape is pressed anywhere in the navigation component, all open sublists close and focus shifts to the topmost parent.
Whether focus is on a link or a button in the component, pressing Escape should trigger a cascade that closes any open sublists on the top row and sets the focus to the top-most parent of the currently focused element.
The easiest way to do this is to pass the necessary information to the common key handler, handleCommonKeyDown and let the focus shift happen in there.
export const handleCommonKeyDown = (e, currentlyFocusedEl, CloseComponentWithFocus, ..., shiftFocus) => {
switch (e.key) {
case Keys.ESC:
const closedEl = closeComponentWithFocus(currentlyFocusedEl);
if (closedEl) {
shiftFocus(closedEl);
}
break;
...
}
};
GitHub (release 0.9.0) - handleCommonKeyDown.ts
Both SubNavigation and NavigationItem send two additional functions down to the handler: CloseComponentWithFocus and shiftFocus.
useNavigation
const closeComponentWithFocus = (focusedEl) => {
closeComponent();
return _getTopRowElement(focusedEl as FocusableElementType);
};
GitHub (release 0.9.0) - useNavigation.tsx - closeComponentWithFocus() - Line 275
The closeComponent function is called, and then the ultimate ancestor at the top of the currently focused element's hierarchy is returned.
const closeComponent = () => {
const { storedList } = _getNavigationObjectByParent(null);
storedList.map((currentElement) => {
if (currentElement.type === "button") {
const { isSubListOpen, dispatchSubListClose } =
_getNavigationObjectByParent( currentElement );
if (isSubListOpen && dispatchSubListClose) {
dispatchSubListClose();
}
}
});
};
GitHub (release 0.9.0) - useNavigation.tsx - closeComponent() - Line 259
The closeComponent function is similar to _closeOpenSiblings, except that all buttons on the top row are triggered to close their open sublists.
Close on Click
AC 4
- Any open sublists close when a pointing device clicks anything outside of the component.
AC 5
- Any open sublist closes when focus leaves the component
If the component can be closed with a press of the Escape key, equity demands that it can also be closed by activating a pointing device outside the component, as well as when exiting the component via the Tab key.
There are a number of click-to-close components out there, but not all of them also handle touch and focus events. I forked a stale repository and renamed it OutsideEventListener.
Adding the OutsideEventListener requires the closeComponent function from the navigation hook, but the Navigation component cannot access it because it has no access to the useNavigation hook. Instead, a NavigationWrapper component is called from the original NavigationComponent, and the <nav /> is moved into the wrapper.
export default function Navigation({
children, cx, isOpen = true, label, orientation = "horizontal", ...rest
}) {
const parentRef = useRef(null);
const navigationContextProps = {
data: {
isSubListOpen: isOpen, storedParentEl: null, storedList: [],
},
};
const navigationListProps = {
...rest, isOpen, orientation, parentRef,
};
const navigationWrapperProps = {
className: cx, label: label,
};
return (<>
<NavigationProvider value={navigationContextProps}>
<NavigationWrapper {...navigationWrapperProps}>
<NavigationList {...navigationListProps}>{children}</NavigationList>
</NavigationWrapper>
</NavigationProvider>
</>);
}
GitHub (release 0.9.0) - Navigation.tsx
Refactoring moved the classes and label from navigationProps to navigationWrapperProps, and the NavigationWrapper component replaces the < nav /> element.
export function NavigationWrapper({
children, cx, label, ...rest
}: NavigationWrapperProps) {
const {closeComponent} = useNavigation();
const navigationProps = {
"aria-label": label, className: cx, ...rest,
};
const outsideElementListenerProps = {
onOutsideEvent: returnTrueElementOrUndefined(isComponentActive(), closeComponent,),
};
return (<OutsideEventListener {...outsideElementListenerProps}>
<nav {...navigationProps}>{children}</nav>
</OutsideEventListener>);
}
GitHub (release 0.9.0) - NavigationWrapper.tsx
The <nav /> element is moved inside the OutsideEventListener, which sends the closeComponent function from the navigation hook to trigger when an outside click or pointer event happens, as well as triggering when focus shifts outside of the component.
Most click-to-close implementations are architected to only be active when the item they are connected to is present and open. That isn't the case with the uncontrolled navigation component, which is present continuously, and I'm uncomfortable with the idea that every click outside it will trigger a close navigation call. This is the scenario that necessitated the fork, ensuring the function can be passed in as undefined when the navigation component isn't active.
IsComponentActive is a flag that determines whether the closeComponent function is sent to the outside event listener. If the flag is false, the function is not passed through, effectively neutering the outside handler.
All that's left is to add the flag and apply the conditions to set it to either true or false.
Adding isComponentActive
The first step is to add the flag into state within the navigation context provider.
const [state, dispatch] = useReducer(navigationReducer, {
navigationArray: [navigationObject], isComponentActive: false,
});
const isComponentActive = () => {
return state.isComponentActive;
};
const setIsComponentActive = (isActive) => {
dispatch({type: "SET_IS_COMPONENT_ACTIVE", isActive});
};
GitHub (release 0.9.0) - NavigationProvider.tsx - Line 28
The flag is added to the state, and two functions are created, one to return the flag and the other to set it via the reducer.
case "SET_IS_COMPONENT_ACTIVE": {
if (state.isComponentActive === action.isActive) return state;
return {...state, isComponentActive: action.isActive};
}
GitHub (release 0.9.0) - navigationReducer.ts - Line 14
With the flag now wired in and added to the NavigationWrapper component, the question becomes where to set it. The flag needs to be set to true when the component is first entered, and to false when focus leaves the component. All of this can be accomplished in the various functions within the navigation hook.
const _handleTopRowItemFocus = (focusedEl) => {
if (isComponentActive()) {
_closeOpenSiblings(focusedEl);
} else {
setIsComponentActive(true);
}
};
GitHub (release 0.9.0) - useNavigation - _handleTopRowItemFocus() /handleLinkFocus() - Line 187
When a component is inactive, the only focusable elements available are on the top row. In this case, the call to close any open siblings only needs to happen if the component is already active, and if it isn't, the component is set to active.
A top-row focus can be triggered by a pointer action on a button or by keyboard navigation.
const closeComponent = () => {
const {storedList} = _getNavigationObjectByParent(null);
storedList.map((currentElement) => {
if (currentElement.type === "button") {
const {isSubListOpen, dispatchSubListClose} = _getNavigationObjectByParent(currentElement as ControllingElementType,);
if (isSubListOpen && dispatchSubListClose) {
dispatchSubListClose();
}
}
});
setIsComponentActive(false);
};
GitHub (release 0.9.0) - useNavigation - closeComponent() - Line 259
The logical place to set the component to an inactive state is, of course, in the closeComponent function.
And with this last piece of code in place, it's time to declare the horizontal uncontrolled navigation component complete! (celebration emoji)
That's not to say the work is finished; if you recall, the requirements required the navigation component to also work as a mobile menu, which means passing through a controlling reference and ensuring the keyboard works as expected in that environment. You can see the issues in this video.
Summary
Accessibility and usability can go hand in hand by ensuring reasonable user expectations are met. Since every user expects components to clean up and reset to a pristine state when they are no longer in use, spending time refining the navigation component to handle these closures is well worth it.
All that's left to do is make sure this component functions when controlled and meets user expectations when navigating a vertical top row rather than a horizontal one.
