DEV Community: ShaynaProductions

Vertical Layout Considerations

ShaynaProductions — Tue, 30 Jun 2026 12:30:00 +0000

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.

This article completes the process of creating a main navigation component that is universally accessible, both perceptually and operatively; can operate in a controlled or uncontrolled state; and is operable when displayed in a horizontal, desktop arrangement as well as in a vertical, mobile scenario.

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 1.0.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 Vertical Alignment along with previous requirements.

Introduction

Up until now, all keyboard handling has been implemented with the default horizontal layout in mind. When displaying vertically, changes are necessary to meet user expectations. Sublists should remain open when focus shifts to a parent's sibling, and the up and down arrow keys should move in the same way as the Tab and Shift + Tab keys.

An uncontrolled, horizontal layout is the default, so the acceptance criteria for this release focus on the differences required for a vertically laid-out component.

Acceptance Criteria

Vertical Alignment

AC 1 - When moving between components in a vertically aligned component. Sublists off the top row will not automatically close.
AC 2 - When setting focus within a vertically aligned component, scrolling is allowed.
AC 3 - When in a vertically aligned component, the DOWN-ARROW key should move to the parent's sibling when the current list is closed
AC 4 - When in a vertically aligned component, the DOWN-ARROW key should move to the parent's sibling when at the bottom of the last opened sublist in a list.
AC 5 - When the last button on the top list is closed, and its last child is the last element in the component, focus should stay on the last button when the DOWN-ARROW key is pressed
AC 6 - When the DOWN-ARROW key is pressed on the last link in the component, focus should stay on the last link.
AC 7 - When the Up-ARROW key is pressed, focus should move up the visible list and end at the first child of the top row.

A controlled component may not always be laid out vertically, and so it stands to reason that the configuration should hold the layout display type. In this case, the orientation prop, passed to the top list, is already available; it just needs to be stored in the NavigationProvider's config object.

Data Setup

const navigationContextProp = {
  data: {
    controllingRef: controllingRef,
    isSubListOpen: isOpen,
    storedParentEl: null,
    storedList: [],
  },
  config: { orientation: orientation, skipName: skipName || "skip" },
};

GitHub (release 1.0.0) - Navigation.tsx - Line 24

The config object contains name/value pairs that remain constant throughout the component's lifetime. Adding anything to the config object in the Navigation component makes it available within the provider. In this case, both orientation and skipName are placed in the config object.

const isLayoutVertical = useCallback(() => {
  return config.orientation === "vertical";
}, [config.orientation]);

GitHub (release 1.0.0) - NavigationProvider.tsx - Line 63

Since a horizontal layout is the default, all that's necessary is to create a function that answers the question "Is the navigation orientation vertical?"

With the necessary data added to the context provider, implementation can begin.

Keeping SubLists Open

AC 1

When moving between components in a vertically aligned component. Sublists off the top row will not automatically close.

Contrary to the default horizontal layout, it feels jarring when sublists close on navigation within a vertical layout.

const _handleTopRowItemFocus = (focusedEl) => {
    let returnEl;
    if (isComponentActive() && !isLayoutVertical()) {
      _closeOpenSiblings(focusedEl);
    }

    ...

  };

GitHub (release 1.0.0) - useNavigation.tsx closeComponentWithFocus() - Line 232

All that's necessary is to execute _closeOpenSiblings only if the component is both active and laid out horizontally.

Allowing Scroll when Focus Shifts

AC 2

When setting focus within a vertically aligned component, scrolling is allowed.

For the most part, scrolling on focus is disallowed in the horizontal layout, but needs to be available when the component is in a vertical orientation. focusableEl.focus({preventScroll: true}) has been a part of the shiftFocus function since the beginning. The issue, of course, is that isLayoutVertical is part of the NavigationProvider, whereas shiftFocus is part of the NavigationListProvider.

export default function NavigationList({ ... }) {
  const { isLayoutVertical } = useNavigation();

  const listContext = {
    isLayoutVertical,
    parentRef: parentRef,
  };
}

GitHub (release 1.0.0) - NavigationList.tsx - Line 22

NavigationList can call the isLayoutVertical function from the navigation hook, since it lives within its context, passing it through to the NavigationList context provider.

export function NavigationListProvider({ children, value }) {
  const { isLayoutVertical, parentRef } = value;
...
return (
    <NavigationListContext.Provider
      value={{
        getCurrentListItems,
        getParentEl,
        isLayoutVertical,
        registerItemInCurrentList,
      }}
    >
      {children}
    </NavigationListContext.Provider>
  );
}

GitHub (release 1.0.0) - NavigationListProvider.tsx - Line

All the provider does is expose the isLayoutVertical function for the companion hook.

export function useNavigationList() {
    const navigationListContextObj = use(NavigationListContext);
    const {
        getCurrentListItems, getParentEl, isLayoutVertical, registerItemInCurrentList,
    } = returnTrueElementOrUndefined(!!navigationListContextObj, navigationListContextObj,);

...

    const shiftFocus = (focusableEl) => {
        focusableEl.focus({preventScroll: !isLayoutVertical});
    };

GitHub (release 1.0.0) - useNavigationList.tsx - Line 34

If the layout is not vertical, then preventScroll is true; if it is vertical, then preventScroll is false, and the browser will scroll if necessary.

Down Arrow Key Implementation

Most of the work in this context involves making the down arrow behave the same as the Tab key. It means making sure the down key follows the visible DOM.

All of the work for the down arrow criteria takes place in the getNextByButton and getNextByLink functions within the useNavigation hook, wrapped in the conditional isLayoutVertical()

const getNextByButton = ({...}) => {
    ...
    if (isLayoutVertical()) {
        // if last in parent list and not last in component, move to parent's next sibling.
        const isLastInComponent = _isLastElementInComponent(buttonEl);

        if (!isSubListOpen && currentList.indexOf(buttonEl) === currentList.length - 1 && !isLastInComponent) {
            const lastTopElement = _getLastElementInTopRow(buttonEl);
            const lastEl = _getLastElementByParent(buttonEl as ControllingElementType,);
            const lastComponentEl = _getLastElementInComponent();
            if (buttonEl !== lastTopElement && lastEl !== lastComponentEl) {
                focusableEl = getFocusableElementFromDOM(lastEl, "next",) as FocusableElementType;
            } else {
                focusableEl = buttonEl;
            }
        }
    }
}

GitHub (release 1.0.0) - useNavigation.tsx getNextByButton() - Line 340

AC 3

When in a vertically aligned component, the DOWN-ARROW key should move to the parent's sibling when the current list is closed

If the layout is vertical, the sublist is not open, and the currently focused element is not the last element within the component, the last element connected to a parent is determined, and the next focusable element in the DOM can be obtained.

AC 4

When in a vertically aligned component, the DOWN-ARROW key should move to the parent's sibling when at the bottom of the last opened sublist in a list.

This criterion is already implemented in the normal getNextByButton handling (lines 335-338) and is mentioned here to support testing.

AC 5

When the last button on the top list is closed, and its last child is the last element in the component, focus should stay on the last button when the DOWN-ARROW key is pressed

const lastEl = _getLastElementByParent(
  buttonEl as ControllingElementType,
);

const lastComponentEl = _getLastElementInComponent();
if (buttonEl !== lastTopElement && lastEl !== lastComponentEl) {
  focusableEl = getFocusableElementFromDOM(
    lastEl,
    "next",
  ) as FocusableElementType;
} else {
  focusableEl = buttonEl;
}

GitHub (release 1.0.0) - useNavigation.tsx - getNextByButton() - Line 350

When the currently focused button is not the first element and the last element descended from it is not the last element in the component, the next focusable element in the DOM is retrieved and returned; otherwise, the same button element currently holding focus is returned.

AC 6

When the DOWN-ARROW key is pressed on the last link in the component, focus should stay on the last link.

if (isLayoutVertical()) {
  const isLinkLastInComponent = linkEl === _getLastElementInComponent();
  if (isLinkLast && !isLinkLastInComponent) {
    focusableEl = getFocusableElementFromDOM(
      linkEl,
      "next",
    ) as FocusableElementType;
  } else if (isLinkLast && isLinkLastInComponent) {
    focusableEl = undefined;
  }
}

GitHub (release 1.0.0) - useNavigation.tsx getNextByLink() - Line 399

Buttons and links are handled slightly differently since only a link can be the last element in any navigation component, and focus only shifts to the next element in the DOM when the link is not the last in the component; otherwise, focus remains where it is since only the TAB key is capable of leaving the component.

Up Arrow Key Implementation

AC 7

When the Up-ARROW key is pressed, focus should move up the visible list and end at the first child of the top row.

The up arrow key works almost the same whether the top row is displayed in either a horizontal or vertical layout.

if (isLayoutVertical()) {
  const { storedList: parentList } =
    _getNavigationObjectByListElement(buttonEl);

  if (_isElementInTopRow(buttonEl)) {
    const prevParentEl = _getPreviousElementInList(
      buttonEl,
      parentList,
    ) as ControllingElementType;


    if (prevParentEl?.type === "button") {
      const lastElement = _getLastElementByParent(prevParentEl);
      const { isSubListOpen } =
        _getNavigationObjectByListElement(lastElement);
      if (isSubListOpen) {
        focusableEl = lastElement;
      } else {
        const prevParentObj = _getNavigationObjectByParent(
          prevParentEl as ControllingElementType,
        );
        if (prevParentObj.isSubListOpen) {
          const lastElement = _getLastElementByParent(prevParentEl);
          const { isSubListOpen, storedParentEl } =
            _getNavigationObjectByListElement(lastElement);

          /* istanbul ignore else */
          if (!isSubListOpen) {
            focusableEl =
              storedParentEl as FocusableElementType;
          }
        }
      }
    }
  }
}

GitHub (release 1.0.0) - useNavigation.tsx getPreviousByButton() - Line 464

The only change on an up-arrow press for vertical alignment occurs when focus is on a button on the top row. In such a case, the previous sibling is found, and if the sibling is a button whose sublist is opened, then the last element in the sibling's sublist should receive focus.

If the sublist is not opened, then focus should shift to the parent button.

Conclusion

This release concludes the development of a fully accessible navigation component as demonstrated by the last two videos.

Demonstration of the completed navigation component, uncontrolled and suitable for desktop.

Demonstration of the completed navigation component as a controlled, vertically aligned component suitable for mobile.

If you've read all these articles, thank you.

Most components don't require the complex keyboard handling and jumping between components as this one has, but every component can benefit from considering the relationship between accessibility needs and architecture.

Creating an accessible component means considering perceivability as it ties to a peripheral. Screen reader users benefit from structural HTML and clearly defined labels and aria-states; screen users benefit from structured HTML and aria-states that can serve as selectors for styling.

Designers and developers have different responsibilities when it comes to working with accessibility. Designers need to have a much more in-depth understanding of the visual deficiencies that need to be accommodated. At the same time, developers focus more on operability for screen/keyboard users and on ensuring that what screen readers send out is useful.

I'll be back at some point with a few articles on an updated theming system. While I'm working on that, I'd love to hear about your experiences implementing the navigation component.

Setting Up a Controlled Component

ShaynaProductions — Thu, 25 Jun 2026 12:30:00 +0000

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 the requirements for delivering an uncontrolled navigation component with a horizontal layout; with full keyboard functionality, along with adding the niceties of closing sublists when lists are closed and making sure any open sublist on the top row closes when focus shifts away from it.

Rather than write an entirely new component for a mobile version, I'm going to modify the existing code. This first article outlines the steps necessary to set up and work with a controlled component.
-—

You can view the requirements for the Controlled Components Release along with previous requirements.

Introduction

Everything up to this point has been built with the default requirement of an uncontrolled component. As a desktop horizontally aligned navigation component, there hasn't been a need to control the component's visibility. If you've been following these articles from the start, you might recall that one of the requirements was for the ability to use the same component as a mobile version, which means a small icon button, typically shown with three horizontal lines, colloquially referred to as a "hamburger menu," which, when triggered, opens a vertically aligned navigation component.

The decision to expand the navigation component to work in a more constrained screen environment means less work, since much of the code already written would have to be replicated.

When adding more or changing existing functionality, accessibility still needs to be considered. What works in one situation may need to be refactored for another. And that's the case when considering how to add controlled-component functionality to an uncontrolled component.

The remaining issues are documented in this video.

Return to Content Links

Acceptance Criteria

Controlled Components
AC 1 - When the controlling element is activated, and the navigation component is closed, the navigation component should open and set focus on the first child in the first row.
AC 2 - When Escape is pressed anywhere in a controlled navigation component, all open sublists close and focus shifts to the controlling element.
AC 3 - When tabbing past the controlling element when navigation is closed, focus skips over the navigation component to the next focusable element.
AC 4 - When SHIFT+Tab is applied to a focusable element just past the closed navigation component, focus skips the component and lands on the controlling element.
AC 5 - When tabbing out of a controlled component, the component should close.

Rather than staying on the icon button once navigation opens, focus should shift to the first focusable element in the navigation component. When the component is closed by pressing Escape, focus should shift back to the icon button.

The difficulty, once again, stems from the architectural decision to place all navigation links within the DOM to facilitate screen reader access via the various elements list (or rotor for VoiceOver). When the navigation component is closed, pressing the Tab key should move focus from the icon button to the first focusable element on the other side of the component. Conversely, if Shift+Tab is used, focus should move from the focusable element on the other side, back to the icon button.

The last acceptance criteria requires the component to close when an outside event is consumed. Since the navigation component also provides an OutsideEventListener, the duplication must be handled so that only one listening component is active.

Return to Content Links

Controlled Component

A component is considered controlled when its states and behaviors are managed by the parent component rather than relying on its own internal code. In this case, a MobileNavigation component toggles its open state when the icon button is activated.

Interaction between the controlling element and the navigation component requires handling focus and determining whether the navigation component is open or closed.

Return to Content Links

<MobileNavigation />

AC 1

When the controlling element is activated, and the navigation component is closed, the navigation component should open and set focus on the first child in the first row.

export function MobileNavigation({
  children,
  cx,
  label,
  skipName = "skip",
  ...rest
}) {
  const [open, setOpen] = useState(false);
  const buttonRef = useRef(null);
  const closeNavigation = () => {
    setOpen(false);
  };

  const handleFocus = () => {
    if (open) {
      closeNavigation();
    }
  };

  const handleKeyDown = (e) => {
    switch (e.key) {
      case Keys.TAB:
        /* istanbul ignore else */
        if (!open) {
          const nextEl = getFocusableElementFromDOM(buttonRef.current, "next");
          nextEl.setAttribute(`data-${skipName}`, "true");
        }
        break;
    }
  };

  const handlePress = (e) => {
    if (!open) {
      const nextEl = getFocusableElementFromDOM(buttonRef.current, "next");
      nextEl.focus({ preventScroll: true });
    }
    setOpen(!open);
  };
  const buttonProps = {
    "aria-expanded": open,
    "aria-controls": "mobile-menu",
    "aria-label": "Navigation Menu",
    id: "mobile",
    isOpen: open,
    onFocus: handleFocus,
    onKeyDown: handleKeyDown,
    onPress: handlePress,
    ref: buttonRef,
    style: { "--component-item-size": 24 } as CSSProperties,
  };

  const iconProps: IconProps = {
    IconComponent: MenuIcon,
    isSilent: true,
  };

  const navigationProps = {
    ...rest,
    cx: cx,
    controllingRef: buttonRef,
    id: "mobile-menu",
    isOpen: open,
    label: label,
    orientation: "vertical" as Orientation,
  };
  return (
    <Box cx="mobile-navigation">
      <Button {...buttonProps}>
        <Icon {...iconProps} />
      </Button>
      <Navigation {...navigationProps}>{children}</Navigation>
    </Box>
  );
}

GitHub (release 1.0.0) - MobileNavigation.tsx

The MobileNavigation component contains and handles the icon button along with the navigation component, setting up event handlers for onFocus (closing the navigation component if it is set to open) and onPress, which, at the moment, simply toggles the open state.

Notice that the button and open state are passed into the Navigation component, along with a new prop, skipName, that creates a unified data attribute on a focusable element to handle focus when the navigation component should be skipped entirely.

In this case, when the navigation component is closed, and a keyboard user presses the Tab key on the icon button, focus should skip the actual component and move to the element on the other side. The data name could be hardcoded, and indeed, there is a default, but it's always a good idea when setting up an interaction between components to allow the data name to be agreed upon by both parties.

When the mobile navigation component sets the open state to true, focus should shift to the first focusable element within the navigation component. Pushing focus into the component helps both screen/keyboard and screenreader/keyboard users.

Return to Content Links

Data Setup

A controlled navigation component needs to keep track of more information than an uncontrolled component. The controllingRef needs to be added to the context provider and sent to the NavigationWrapper, along with the open state.

export default function Navigation({
  children,
  controllingRef,
  cx,
  isOpen = true,
  label,
  orientation = "horizontal",
  SkipName,
  ...rest
}: NavigationProps) {
    const parentRef = useRef(null);
    const uncontrolledRef = useRef(null);
    const mergedRef = useMergedRef(uncontrolledRef, controllingRef,);

    const navigationContextProps: NavigationContextStoredValueProps = {
        data: {
            controllingRef: mergedRef, isSubListOpen: isOpen, storedParentEl: null, storedList: [],
        }, config: {skipName: skipName || "skip"},
    };
}

GitHub (release 1.0.0) - Navigation.tsx

While the controllingRef is managed in the data object, a new object is also being passed to the context provider, config. Any elements in the config object should be considered stable and non-changeable.

  const navigationListProps: NavigationListProps = {
    ...rest,
    isOpen,
    orientation,
    parentRef,
  };

  const navigationWrapperProps = {
    cx,
    controllingRef,
    isOpen,
    label: label,
  };

  return (
    <NavigationProvider value={navigationContextProps}>
      <NavigationWrapper {...navigationWrapperProps}>
        <NavigationList {...navigationListProps}>{children}</NavigationList>
      </NavigationWrapper>
    </NavigationProvider>
  );

GitHub (release 1.0.0) - Navigation.tsx

The controlling reference needs to be stored and retrieved to shift focus back to the button when the Escape key is pressed. The controlling reference is not the parentRef; for a top-row navigation object, the parentRef will always return as null and be passed through to the top-level list. The controlling reference is not only passed to the data object but also to the NavigationWrapper.

NavigationProvider.tsx

Before anything, the controllingRef needs to be set up in the reducer. The config object is simply destructured and is ready to return information.

export function NavigationProvider({ children, value }) {
  const { data, config } = value;
  ...

  const [state, dispatch] = useReducer(navigationReducer, {
    navigationArray: [navigationObject],
    isComponentActive: false,
    controllingRef: data.controllingRef,
  });
  ...
  const getControllingElement = useCallback(() => {
    return returnElementFromRefObject(state.controllingRef);
  }, [state.controllingRef]);

const isComponentControlled = useCallback(() => {
  return getControllingElement() !== null;
},[getControllingElement]);

const getSkipName = useCallback(() => {
  return config.skipName;
}, [config.skipName]);

 ...
  return (
    <NavigationContext.Provider
      value={{
        getControllingElement,
        ...,
        isComponentControlled,
        ...
      }}
    >
      {children}
    </NavigationContext.Provider>
  );
}

GitHub (release 1.0.0) - NavigationProvider.tsx

Three functions are added to the context provider: getControllingElement, which returns the actual element stored; isComponentControlled, which returns false if the controlling element is null; and getSkipName, which returns the value from the config object.

The controllingRef is added to the reducer. Since the controlling reference will never change once the mobile navigation button renders, there's no need to add extra code to the reducer.

With the data set up, it's time to implement the functionality.

Return to Content Links

Close on Escape

AC 2

When Escape is pressed anywhere in a controlled navigation component, all open sublists close and focus shifts to the controlling element.

The next criterion to implement is also the easiest; all that's necessary is to modify closeComponentWithFocus inside the useNavigation hook.

const closeComponentWithFocus = (focusedEl) => {
  closeComponent();

  const controllingElement = getControllingElement();
  return controllingElement !== null
    ? controllingElement
    : _getTopRowElement(focusedEl);
};

GitHub (release 1.0.0) - useNavigation.tsx closeComponentWithFocus() - Line 310

When Escape is pressed, and the component is controlled, focus should shift to the controlling element rather than the top-level parent of the currently focused item.

Return to Content Links

Passthrough When Closed

AC 3

When tabbing past the controlling element after navigation is closed, focus skips the navigation component and moves to the next focusable element.

As a result of the architectural decision to keep all links in the DOM, tabbing on the mobile button should pass through the component to the focusable element on the other side. Realistically, the mobile navigation has no idea how to do that; it has no way of reaching into the navigation component to find the last element and shift focus beyond the navigation component when tabbing off its icon button.

const handleKeyDown = (e) => {
  switch (e.key) {
    case Keys.TAB:
      if (!open) {
        const nextEl = getFocusableElementFromDOM(buttonRef.current, "next");
        nextEl.setAttribute(`data-${skipName}`, "true");
      }
      break;
  }
};

GitHub (release 1.0.0) - MobileNavigation.tsx - handleKeyDown Line 35.

The challenge is how to communicate to the navigation component that, when it receives focus, it should immediately shift outside the component. The solution is to set a data attribute on the first focusable element in the component that instructs the element to shift. The skipName is the same one passed through to the navigation component.

const _handlePassthroughNavigation = (focusedEl) => {
  const shouldSkip = focusedEl.getAttribute(`data-${getSkipName()}`);

  let returnEl;
  if (shouldSkip) {
    const lastElement = _getLastElementInComponent();
    focusedEl.removeAttribute(`data-${getSkipName()}`);
    returnEl = getFocusableElementFromDOM(lastElement, "next");
  }

  return returnEl;
};

const _handleTopRowItemFocus = (focusedEl) => {
  let returnEl: FocusableElementType | undefined;
  if (isComponentActive()) {
    _closeOpenSiblings(focusedEl);
  }

  if (isComponentControlled() && _isFirstElementInComponent(focusedEl)) {
    returnEl = _handlePassthroughNavigation(focusedEl);
  }
  if (!isComponentActive()) {
    setIsComponentActive(true);
  }

  return returnEl;
};

GitHub (release 1.0.0) - useNavigation.tsx- _handlePassthroughNavigation - Line 218

If a skip data attribute exists on the focused element, the last component element is found and returned to shift outside the component. The call to the _handlePassthroughNavigation function is made only if the component is controlled, and focus is currently on the first element in the top row.

The issue with Tabbing through a closed navigation component is now resolved.

AC 4

When SHIFT+Tab is applied to a focusable element just past the closed navigation component, focus skips the component and lands on the controlling element.

Just as a check was made when the currently focused element was the first focusable element in a component, shifting focus to the mobile button needs to happen when focus is on the last focusable element in the component.

const _handleLastChildFocus = (focusedEl) => {
  const { isSubListOpen } = _getNavigationObjectByListElement(focusedEl);
  if (!isSubListOpen) {
    setIsComponentActive(false);
    if (isComponentControlled()) {
      return getControllingElement();
    } else {
      return _getLastElementInTopRow(focusedEl);
    }
  }
};

GitHub (release 1.0.0) - useNavigation.tsx - _handleLastChildFocus - Line 280

Code has been added to check if the component is controlled only when the sublist the focusable element is a part of is not open. If this is the case, the controlling element is returned rather than the last element in the top row.

Return to Content Links

Component Closing

AC 5

When tabbing out of a controlled component, the component should close.

When the focus shifts outside of the mobile navigation component, the component should become invisible on the screen. This requires an OutsideEventListener in the Mobile component to capture clicks and blurs outside the component and close it. But the uncontrolled component also has the same listener, and having two of them can create issues.

if (isComponentControlled()) {
  return <nav {...navigationProps}>{children}</nav>;
} else {
  return (
    <OutsideEventListener {...outsideElementListenerProps}>
      <nav {...navigationProps}>{children}</nav>
    </OutsideEventListener>
  );
}

GitHub (release 1.0.0) - NavigationWrapper.tsx - Line 49

The solution, of course, is only to load the listener in the NavigationWrapper when the component is uncontrolled.

export function MobileNavigation({ ... }){
  ...
  const outsideEventProps = {
    onOutsideEvent: returnTrueElementOrUndefined(open, closeNavigation),
  };

  ...
  return (
    <OutsideEventListener {...outsideEventProps}>
      <Box cx="mobile-navigation">
        <Button {...buttonProps}>
          <Icon {...iconProps} />
        </Button>
        <Navigation {...navigationProps}>{children}</Navigation>
      </Box>
    </OutsideEventListener>
  );
}

GitHub (release 1.0.0) - MobileNavigation.tsx - Line 74

Adding the OutsideEventListener and requiring the close function to be called only when the navigation component is open solves the last issue when a component is controlled.

And with that, the last of the issues surrounding a controlled component are solved.

Return to Content Links

Summary

Adding functionality to allow a component to be controlled requires a new look at keyboard functionality and confirming keyboard focus works both when the controlled component is on the screen and when it is not. It means making sure there are no conflicts with competing utilities when the component is controlled versus when it is not.

The next article will address the remaining issues with the vertical layout, and the navigation component will be ready for use in production.

Styling the Vertical - Achieving Parity

ShaynaProductions — Tue, 23 Jun 2026 12:30:00 +0000

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. A page showcasing these base components may be run locally through this release.

The design requirements for this release are available.

-—

Content Links

Introduction
Layout
Appearance
- <nav / >
- Generic Styling
- Reimagining Focus and Hover
- Achieving Parity
- aria-current
- Refinements
- Summary

Introduction

With only one more release coming up and the horizontal layout styling complete, now is the time to focus on completing vertical layout styling. Most of the layout itself was completed in an earlier release and described in the article Laying it all out on the vertical.

When styling a component, care must be taken to ensure parity with the information provided by screen readers through some aria attributes. For instance, a navigation component must set the aria-current="page" attribute on a link whose href points to the current page. In the example being shown, the link in question is the "by Era" link, under Find Your Next Story and Tales.

)

While screen reader users hear which button or link is the item currently capturing focus, styling is needed to achieve the same for screen users. Visual styling is necessary to guarantee that visual and auditory/tactile users have the same information.

Layout

@layer system-component {
  div.vertical {
    position: relative;
  }
  nav.vertical-navigation {
    min-width: calc(var(--sp-px) * 320);
    position: absolute;
    top: calc(var(--sp-px) * 24);
    width: 30%;
    z-index: 3;

    /* Layout */
    & > ul {
      & > li {
        & > button,
        & > a[href] {
          justify-content: flex-start;
        }

        /*sub navigation (not top row)*/
        & > ul {
          & li {
            width: 100%;
          }

          & > li {
            & button,
            & a[href] {
              flex-wrap: nowrap;
              justify-content: flex-start;
            }
          }
        }
      }
    }
  }
}

GitHub (release 0.9.0) - styledVertical.css

The earlier layout has been moved to the top of the style sheet, and all padding has been removed; a width of 30% is set, with a minimum width constraint of 320 relative pixels. The entire nav element is set to relative positioning. While some media queries regarding size would be useful here, I'm going to forgo them in this styling context. The nav element is absolutely positioned within a containing div that is relatively positioned and shifted down slightly to create more white space between the description and the nav element.

With the layout complete, attention turns to styling the nav element.

Appearance

<nav / >

/* Appearance */
/* nav */
nav.vertical-navigation {
  border-color: var(--purple-7);
  border-style: solid;
  border-width: calc(var(--sp-px) * 1);
  box-shadow: calc(var(--sp-px) * 7) calc(var(--sp-px) * 7) calc(
      var(--sp-px) * 7
    ) oklch(var(--raw-purple-4) / 0.4);
  padding: calc(var(--sp-px) * 8) calc(var(--sp-px) * 16);
  padding-left: calc(var(--sp-px) * 20);
}

Styling the nav element with borders visually distinguishes the nav component and groups the nested lists. A box shadow is applied to the right and bottom to create the illusion of depth.

Generic Styling

List items, buttons, and links need some generic styling, much of which was applied in the earlier version.

& li {
  border-color: transparent;
}
& button,
& a[href] {
  background-color: transparent;
  border-color: transparent;
  border-bottom-color: var(--purple-3);
  border-radius: 0;
  border-style: solid;
  border-width: calc(var(--sp-px) * 1);
  border-left-width: calc(var(--sp-px) * 2);
  display: flex;
  font-weight: 400;
  padding: calc(var(--sp-px) * 4);
  text-decoration: none;
  white-space: nowrap;
  width: 100%;
  &:focus-visible {
    outline: none;
  }
}

Border colors are removed on the list items. List items cannot display borders since a list would show a border for all the elements in a nested list along with the button and that's not the styling I'm attempting to achieve.

Buttons and links are styled together. Since everything will be clickable, text decoration is removed, while font weight and base padding are standardized. A width of 100% is applied to ensure the focusable element fills the list item it is contained in. This again ensures the target area is at least 24 relative pixels wide, while the target height is determined by the font-size (16 relative pixels) plus the 4 relative pixels of padding applied to the top and bottom.

Reimagining Focus and Hover

& button,
& a[href] {
  … &:focus-visible {
    outline: none;
  }
  &:hover,
  &:focus {
    border-left-color: var(--purple-7);
  }
}

A focus outline can look terrible when focusable elements are part of a list, so the outline is set to none, and further focused styling needs to be applied.

Adding color to the left border to the focusable elements allows the user to know where the cursor or target pointer is. This again achieves parity with the information coming from a screen reader which announces each link or button as it attains focus.

Achieving Parity

aria-current="page"

As stated earlier, a screen reader can announce to a user when a link references the page the user is currently visiting. To achieve parity, a visual cue should be styled to inform a screen-focused user of the same.

nav.vertical-navigation {
  ... & a[href][aria-current="page"] {
    &:before {
      color: var(--purple-8);
      content: "\25C9";
      position: absolute;
      left: calc(var(--sp-px) * 4);
    }
  }
}

Any link in the navigation may include the aria-current attribute, so styling is applied by placing the selector directly under the nav element. A fisheye unicode character is applied, and positioned 4 relative pixels to the left of the link element. Even though the visual is associated with the link, the character is positioned outside of the element.

Refinements

With almost all the styling completed, it's time for some refinements, specifically, the bottom border under the About button should be removed, and sublists should be indented without affecting the current left border.

nav.vertical-navigation {
  ... 
  & > ul > li {
    &:last-child {
      & > button,
      & > a[href] {
        border-bottom-color: transparent;
      }
    }

    & ul > li {
      & button,
      & a[href] {
        padding-left: calc(var(--sp-px) * 16);
      }

      & > ul > li {
        & button,
        & a[href] {
          padding-left: calc(var(--sp-px) * (16 * 2));
        }
      }
    }
  }
}

The bottom border only needs to be removed from the last child in the top set of navigational elements. In keeping with the requirements to reduce shifting, the border bottom color is set to transparent rather than removed altogether.

Because I want the left border to remain in place, I have to shift the left padding of a focusable element, and this must be done at every level of the subnavigation.

With this last code in place, the vertically styled navigation is complete!

Summary

The Ins and Outs of Closings

ShaynaProductions — Thu, 18 Jun 2026 12:30:00 +0000

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.

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.

You can view the requirements for the Closings and Exit Release along with previous requirements.

Content Links

Introduction
Acceptance Criteria
Closing Sublists on Parent Close
Top Row
Close Component
- Close on Escape
- Close on Click
Summary

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.

Return to Content Links

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.

Return to Content Links

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.

Focus Issues and Refinement Support

ShaynaProductions — Tue, 16 Jun 2026 12:30:00 +0000

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.

My last development article completed the base requirements for keyboard functionality within the component; attention now shifts to adding some of the last functionality required, closing sublists when the lists holding them now close and determining what happens when a closed component is entered via the keyboard through the Tab and Shift+Tab keys.

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.8.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, 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.

You can view the requirements for the Focus and Refinement Support Release along with previous requirements.

Content Links

Introduction
Acceptance Criteria
Entering
Closings
- Setting Up For Success

Introduction

The implementation of keyboard handling left one obvious keyboard issue to fix: an apparent keyboard trap that occurs when focus shifts into the component via a Shift+Tab key combination.

In addition to the keyboard trap, other issues arise that, while not errors, can be refined to meet user expectations. Closing sublists when a parent is closed, or closing open lists when navigating through the top row, will give the component a finished aspect.

This release, while fixing one nagging issue, once again focuses on the internal, foundational aspects necessary to support those requirements and sets up the next release for success, enhancing the component to close cleanly, beginning with additions to the NavigationProvider.

Acceptance Criteria

Focus and Closing Foundation Release

AC 1 - When Shift+Tab is used to enter the component and the last child on the top row is a button, focus should land on that button

A navigation component is not modal; it does not block interaction with other elements on a page, and exiting can be done using the Tab and Shift+Tab keys on the first and last component elements.

As a reminder, the entire component is always in the document object model, meaning that when Shift+Tab is executed to shift focus into the component, there's a good chance the focus will initially land on a link in an unexpanded sublist. In that case, the focus should shift to its parent on the last row.

For the last component element, if it is contained in an unexpanded sublist, focus should shift to its parent on the last row.

Entering

AC 1 fixes the last remaining keyboard-related issue, which occurs when Shift+Tab moves focus from outside the component to the last focusable element in the navigation component. If the top-row parent is a button and the sublist containing the last focusable element is closed, focus should shift to the top-row parent.

Any disappearance of the focus outline is regarded as an error by a screen-perceiving, keyboard-operating user.

The solution is to shift the focus to the top-row parent when focus is placed on the last element of the component within a closed sublist. This requires another event listener, onFocus.

Navigation Item

const handleFocus = () => {
  const linkEl = linkRef.current;
  const focusableEl = handleLinkFocus(linkEl);
  if (!!focusableEl && focusableEl !== linkEl) {
    shiftFocus(focusableEl);
  }
};

...
const linkProps = {
  ...,
  onFocus: handleFocus,
  onKeyDown: handleKeyDown,
  ref: linkRef,
  ...rest,
};

GitHub (release 0.8.0) - NavigationItem.tsx - Line 79

The handleFocus function calls the useNavigation hook's handleLinkFocus function, which can return a new element to shift focus. The function may also return the current link element. The focus should shift only when the returned element is both defined and different.

UseNavigation

HandleLinkFocus


const handleLinkFocus = ( linkEl) => {
  if (_isLastElementInComponent(linkEl)) {
    return _handleLastChildFocus(linkEl);
  } 
};

GitHub (release 0.8.0) - useNavigation.tsx - HandleLinkFocus Line 369

The last element of a component is always a link, so a check is implemented to determine whether the link holding focus is the last component element; if so, the handler for the last child is called, which will either return itself or its topmost ancestor on the top row.

_isLastElementInComponent

const _isLastElementInComponent = (focusedEl) => {
    return focusedEl === _getLastElementbyComponent();
  };

GitHub (release 0.8.0) - useNavigation.tsx - _isLastElementInComponent Line 153

The question of whether the currently focused element is the last component requires the system to know which element is the last in the component.

_getLastElementInComponent

const _getLastElementInComponent = () => {
    let lastEl = lastComponentElement;
    if (!lastEl) {
      const lastElement = _getLastElementInIndexedList(0);
      if (lastElement.type === "button") {
        lastEl = _getLastElementByParent( lastElement  );
      } else {
        lastEl = lastElement;
      }
      setLastComponentElement(lastEl);
    }
    return lastEl ;
  };

GitHub (release 0.8.0) - useNavigation.tsx - _getLastElementByComponent Line 95

Determining the last element of the component involves finding the last focusable element associated with a particular parent, which, in this case, would be the last element in the top row. The _getLastElementByParent function triggers a recursive call, which can be resource-intensive. Since the entire nested list resides in the DOM, the last element will not change, so it makes sense to store it in state on the first call.

If the link is the last element within the component, a specific handler for that condition is called.

_handleLastChildFocus

const _handleLastChildFocus = (focusedEl) => {
    const { isSubListOpen } =  _getNavigationObjectByListElement(focusedEl);
    if (!isSubListOpen) {
      return _getLastElementInTopRow(focusedEl);
    } else {
      return focusedEl;
    }
  };

GitHub (release 0.8.0) - useNavigation.tsx - _handleLastChildFocus Line 203

The only way focus can land on an item in a sublist that has not been expanded is through the Shift+Tab action, at which point the last element in the top row is returned for the focus shift. The currently focused element is returned when the sublist is opened.

_getLastElementInTopRow

const _getLastElementInTopRow = (focusedEl) => {
    const lastTopEl = _getLastElementInIndexedList(0);
    if (lastTopEl.type === "button") {
      const lastEl = _getLastElementByParent(
        lastTopEl as ControllingElementType,
      );
      /* istanbul ignore else */
      if (focusedEl === lastEl) {
        return lastTopEl;
      }
    }
  };

GitHub (release 0.8.0) - useNavigation.tsx - _getLastElementInRow Line 116

If the last element on the top row is a button, the recursive function is called to request the last component element associated with the last element in the top row; if the link matches, the last element on the top row is returned, and the issue is fixed.

Retrieving the last element in the top row first requires fetching the last element in that row.

_getLastElementInIndexedList

const _getLastElementInIndexedList = useCallback(
    (index) => {
      const { storedList } = getNavigationArray()[index];
      return storedList[storedList.length - 1];
    },
    [getNavigationArray],
  );

GitHub (release 0.8.0) - useNavigation.tsx - _getLastElementInIndexedList Line 74

And now, focus shifts to the end button when the component is entered through Shift+Tab.

With the last keyboard issue resolved, attention can be turned to closing scenarios.

Closings

What should happen when an open list containing other open sublists is closed? In the current iteration, nothing happens, meaning that when a list is reopened, any previously opened sublists remain visible.

When thinking about navigation, it can be helpful to look at the requirements for menus, whether they be operating systems or browser applications. In either case, when a list is closed, any open lists under it are also closed.

The question is: how can this be accomplished within the current architecture? While a button in the SubNavigation component can close the list it is associated with, how can it reach into another open subnavigation component in its downline and trigger the close?

Storing the closeSubNavigation function in the associated navigation object should do the trick. Each function can be held and passed by reference, and executing the passed function will call the appropriate functions.

Setting up for Success

Functions shouldn't be stored in state; triggering them there can cause re-rendering, which could be detrimental to data stability. Instead, a map object is created within a reference object, which holds the functions associated with the parent element. This map object can inject the appropriate functions into the navigation array objects when requested.

Since all the data used to manage the navigation component is stored in the navigation context provider, updates to that data are required.

_dispatchSubListCloseByParent

const _dispatchSubListCloseByParent =
  useRef(new Map());

GitHub (release 0.8.0) - NavigationProvider.tsx - _dispatchSubListCloseByParent Line 46

Unlike updates to state, updates to a ref held within the context provider don't trigger a re-render when the map object changes.

getNavigationArray

const getNavigationArray =  useCallback(() => {
    return state.navigationArray.map((obj) => ({
      ...obj,
      dispatchSubListClose: _dispatchSubListCloseByParent.current.get(
        obj.storedParentEl,
      ),
    }));
  }, [state.navigationArray]);

GitHub (release 0.8.0) - NavigationProvider.tsx - getNavigationArray Line 49

The function returning the navigation array is updated to inject the subListClose function as dispatchSubListClose into the array when it is returned. The function isn't part of the state holding the array of navigation objects; it's injected each time the function is called.

registerButtonAsParent

const registerButtonAsParent = (isListOpen, parentEl, dispatchSubListClose) => {
    dispatch({ type: "SET_PARENT", parentEl, isListOpen });
    _dispatchSubListCloseByParent.current.set(parentEl, dispatchSubListClose);
  };

GitHub (release 0.8.0) - NavigationProvider.tsx - registerButtonAsParent
Line 59

RegisterButtonAsParent is also modified, setting the map directly and tying the close function to the parent element.

All that's left to do is to add the close function in the correct useEffect.

SubNavigation

useEffect(() => {
  if (buttonRef.current !== null) {
    registerItemInCurrentList(buttonRef.current as FocusableElementType);
    registerButtonAsParent(
      isSubListOpen,
      buttonRef.current,
      closeSubNavigation,
    );
  }
}, [buttonRef, closeSubNavigation, isSubListOpen, registerButtonAsParent, registerItemInCurrentList]);

GitHub (release 0.8.0) - SubNavigation.tsx - Line 83

With registration complete, work on actually closing the sublists can begin and will be detailed in the next article.

Summary

With keyboard navigation (finally) completed, attention now turns to refinements; fixing the last entry issue by sending focus to the last button in the top row when the last element in the component receives focus in an unopened list and preparing architecture to support each button closing itself and any open sublists maintained by its children.

Styling and Color

ShaynaProductions — Thu, 11 Jun 2026 12:30:00 +0000

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 design article, I demonstrated how structural HTML and nested CSS are natural allies, allowing for concise layout code.

With a layout now applied, focus can shift to adding color to the component, with all that entails.

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.7.0. Links in the article will take you to the proper file in the tagged GitHub Repository.

The design requirements for this release are available.

Content Links

Introduction

In an earlier article, I went through the process of styling a layout on an uncontrolled horizontal navigation component. With that now complete, focus can start on adding color to the component.

Up until this point, I've managed to skirt the issue of accessibility by focusing on perceivable developing for peripherals, screen readers and screens. As I mentioned in an earlier article, The Modality of Accessibility I've found it's easier to focus on peripheral development than try to invoke compassion.

But when it comes to design, dispassion disappears. Adding color to a component means remembering that not everyone has the same visual acuity as the designer. We need to be comfortable with the knowledge that not everyone will have the same experience viewing what's on the screen, and what's more, we shouldn't expect them to.

When it comes to colors, the contrast between foreground and background is not the only consideration; we also need to understand how people actually perceive color and the differences in how they do so.

Our eyes contain three types of cones, specialized photoreceptors, which enable us to differentiate colors. Approximately 1 in 20 people, about 5% of the population, have issues with these cones that limit or change the way they see color. The most common form of color blindness affects men (1 in 12) much more than it affects women (1 in 200).

Color Blindness

Not everyone is color blind in the same way. Some people have issues with the cones in their eyes that distinguish red, while others have difficulties with the cones that distinguish green or blue. But how can a person with normal vision know what a color blind person will see?

Some browsers, notably Google Chrome and Microsoft Edge, both based on Chromium, include a rendering tab that allows evaluating how users with vision impairments will perceive a page. Storybook also has an accessibility addon that includes a vision filter, which has been available since version 8.

I'm going to focus on the browser tools, since not everyone uses Storybook. The easiest way I've found to open the render tab is to open dev tools (F12), then press Escape to open the tab panel. If the render tab isn't showing, click the chevron in the menu to open it.

The Render tab offers many useful options for working on a design. One option is the dropdown "Emulate vision deficiencies". Activating the drop-down shows emulations for blurred vision, reduced contrast, protanopia (no red), deuteranopia (no green), tritanopia (no blue), and achromatopsia (no color). Use these tools to determine how your work looks to those who live with these issues.

When designing with color blindness in mind, the focus is not on the specific color so much as on ensuring the displayed colors have sufficient contrast for differentiation. WCAG 1.4.11 Non-Text Contrast is the applicable success criterion; while WCAG 1.3.3 Sensory Characteristics and WCAG 1.4.1 Use of
Color also comes into play as adjuncts to the non-text contrast.

Instructions that include sensory characteristics, such as "press the red outlined button," aren't useful for someone who cannot see red, or for someone whose color vision is reduced or damaged, or for someone who sees no color at all. The same is true when common color conventions, such as red text indicating an error, are displayed without any distinct information that the text is an error message.

Specific colors aren't the issue; the main thrust of color accessibility is ensuring that a color change is discernible and that all screen users can see the difference.

As a test, I'm going to set the backgrounds of the buttons and links in the sublists to green and red, differing only in hue. Saturation and lightness are consistent. The HSL color space makes it really easy.

& button {
background-color: hsl(120deg 73.44% 74.9%);
}
& a[href] {
background-color: hsl(10.38deg 73.44% 74.9%);
}

I've provided an animated GIF to demonstrate the color changes using the developer tools to render the different emulations.

When colors are highly saturated, the contrast is enough to allow their use together, even when they are green and red. But what happens when colors are less saturated?

& button {
  background-color: hsl(120deg 33.44% 74.9%);
}
& a[href] {
  background-color: hsl(10.38deg 33.44% 74.9%);
}

Lower saturation reduces the color contrast to a level insufficient for users with Deuteranopia (no green) or Achromatopsia (no color).

Saturation is the main culprit when it comes to color contrast issues. You can use desaturated colors; just make sure to check them so the message you are sending isn't lost.

Styling for Appearance

The last time I demonstrated CSS layouts, I combined some appearance into the CSS. I prefer to separate layout and appearance code into two sets of CSS nested structures, and in doing so, I've moved all appearance type styles, colors, padding and borders into their own cascade.

The full stylesheet may be found in the Tab Handling Release 0.7.0 styledHorizontal.css)

@layer system-component {
  nav.horizontal-navigation {
    /* Layout */
    --min-list-width: var(--sp-px);
    padding: calc(var(--sp-px) * 16) 0;
    position: relative;

    /* Top Row nav > ul > li */

    & > ul {
      align-items: normal;
      justify-items: flex-start;
      column-gap: calc(var(--sp-px) * 24);

      & > li {
        display: flex;
        align-content: center;
        align-items: center;
        position: relative;

        /* sub navigation (not top row) */

        & > ul {
          min-width: var(--min-list-width);
          position: absolute;
          top: calc(var(--sp-px) * 36);
          width: fit-content;
          z-index: 3;

          & li {
            width: 100%;
          }

          & > li {
            & button,
            & a[href] {
              display: flex;
              flex-direction: row;
              flex-wrap: nowrap;
              justify-content: flex-start;
            }
          }

          & ul {
            position: relative;
            row-gap: unset;
            width: 100%;
          }
        }
      }
    }
  }
}

The layout style removes all appearance-related values, leaving a clean stylesheet with nothing extraneous cluttering it up. Another selector pattern is replicated for appearance, with any padding references moved into it.

/* Appearance */
nav.horizontal-navigation {
    & > ul {
        & > li {
            & > button,
            & > a[href] {
                padding-left: 0;
            }

            /* sub navigation (not top row) */

            & > ul {
                padding: 0;

                & li {
                }

                & > li {
                    &:first-child {
                        padding-top: calc(var(--sp-px) * 8);
                    }

                    &:last-child {
                        padding-bottom: calc(var(--sp-px) * 8);
                    }

                    & button,
                    & a[href] {
                        padding: calc(var(--sp-px) * 8) calc(var(--sp-px) * 16) 0 calc(var(--sp-px) * 8);
                    }
                }

                & ul {
                    padding: 0 calc(var(--sp-px) * 16) 0 0;

                    & > li {
                        padding-left: calc(var(--sp-px) * 16);
                    }
                }
            }
        }
    }
}

Appearance styling can now be applied, specifically to the generic buttons and links.

/* Generic */

nav.horizontal-navigation {
white-space: nowrap;

& button,
& a[href] {
  background-color: transparent;
  border-color: transparent;
  border-radius: 0;
  border-style: solid;
  border-width: calc(var(--sp-px) * 1) calc(var(--sp-px) * 3);
  color: var(--component-text-color);
  text-align: left;
  width: 100%;
  }
}

Navigation labels should be short, but I'd rather expand the list width than have them wrap. Notice the border width is applied, even though no border (border-color: transparent) is applied. I've standardized my CSS to apply box-sizing: border-box on all elements, which means my borders sit on top of the background, and any change to the border width affects the content width. To minimize visual shifting, I pre-set the border-width and set the color to transparent until a border is necessary.

Buttons and links are set to 100% to fill the list element they reside in. This helps increase the target size for operability via a pointer, such as a mouse, trackpad or finger, especially for those with shaky hands.

Defining State Changes

Focusable elements need to reflect their states: hover, focus and active. Focus is to the keyboard, as hover is to a pointer. The focus-visible pseudo-class handles the outline, which can indicate the current cursor position to a screen/keyboard user. Focus and hover can be set together to provide the same visual styling regardless of how a screen reader user interacts with the element.

& > ul {
    & > li {
        & > button,
        & > a[href] {
            border-bottom-width: calc(var(--sp-px) * 3);
            border-bottom-color: transparent;
            font-weight: 500;
            min-width: calc(var(--sp-px) * 60);
            padding: calc(var(--sp-px) * 8) 0;
            padding-right: calc(var(--sp-px) * 24);
            text-decoration: none;

            & svg {
                background-color: transparent;
            }

            &:focus-visible {
                outline: calc(var(--sp-px) * 1) solid var(--purple-4);
            }

            &:focus,
            &:hover {
                border-color: transparent;
                border-bottom-color: var(--purple-5);
            }

            &:active {
                background-color: var(--purple-2);
                border-bottom-color: var(--purple-5);
            }
        }
    }
}

Whether a user hovers over a focusable element or tabs to it, the cursor pointer should change to indicate that the item can be interacted with; this happens automatically when working with focusable HTML elements, but may need to be added when creating more complex widgets. Colors and borders can be added, removed or changed to indicate the state. When using colors to indicate these state changes, make sure the colors have sufficient saturation and contrast to signal the change to the user.

The styling adds a bottom border that seems to float under the text of the top-row buttons and links and changes on focus, hover or when the element is active.

Styling the SubLists

The CSS originally applied to the sublist navigation is modified to remove gaps and refine the borders around the enclosing list.

& > ul > li {
  & > ul {
    background-color: var(--component-background);
    border-color: var(--gray-4);
    border-style: solid;
    border-width: calc(var(--sp-px) * 1);
    border-radius: calc(var(--sp-px) * 10);
    box-shadow: calc(var(--sp-px) * 7) calc(var(--sp-px) * 3) calc(
        var(--sp-px) * 5
      ) oklch(var(--raw-purple-4) / 0.4);
    gap: unset;
    padding: 0;
    & li,
    & li ul {
      gap: unset;
    }
  }
}

The dropdown corners have been slightly rounded, and a box shadow has been added to create subtle depth. Unfortunately, color space functions like oklch() and hsl() will not respond to design token changes for either the color or the opacity, so I've hard-coded a color and opacity into the box shadow color.

& > ul > li {
    & > ul {
        & li {
            border-bottom-width: calc(var(--sp-px) * 1);
            border-bottom-style: solid;
            border-bottom-color: var(--purple-5);

            &:last-child {
                border-bottom-color: transparent;
            }
        }

        & li > button[aria-expanded="true"] {
            border-bottom-width: calc(var(--sp-px) * 1);
            border-bottom-style: solid;
            border-bottom-color: var(--purple-5);
        }
    }
}

I want the bottom border of a list item in a sublist to change depending on whether the sublist is showing. I can do this by checking whether the button has aria-expanded="true". If the condition can be met by aria or another attribute, use it instead of adding yet another class.

Outline on Focus

  & > li {
    & button,
    & a[href] {
        border-bottom-color: var(--purple-3);
        border-bottom-style: solid;
        border-bottom-width: calc(var(--sp-px) * 1);
        font-weight: 400;
        padding: calc(var(--sp-px) * 8) calc(var(--sp-px) * 16) calc(
                var(--sp-px) * 8
        ) calc(var(--sp-px) * 8);
        text-decoration: none;

        &:focus-visible {
            outline: none;
        }

        &:focus,
        &:hover {
            background-color: var(--purple-1);
            border-left-color: var(--purple-6);
        }

        &[aria-current="page"] {
            border-right-color: var(--purple-5);
        }
    }

    &:has(:focus),
    &:has(:hover) {
        border-left-color: var(--purple-6);
    }
}

& ul {
    padding: 0 calc(var(--sp-px) * 16) 0 0;

    & > li {
        & button,
        & a[href] {
            padding-left: calc(var(--sp-px) * 24);
        }
    }
}

}

I've removed the underlines from links, so buttons and links are harmonized, and I've removed the outline style for focusable elements. I did not do this lightly. Every focusable item should indicate when it receives keyboard focus, and every browser defaults to an outline circle, which, while it can be restyled, should only be removed when something else is set up to replace it, which is for hover and focus.

I'm styling the list item when a button or link receives hover or focus using the :has() pseudo-class, which allows me to style a parent based on an attribute available on a child, in this case, a button or link's hoverable or focusable state.

If a link in a navigation item points to the page a user is currently on, a screen reader may announce it via the aria-current attribute. This conforms to the success criterion 1.3.1 Info and Relationships, which is a catchall for all scenarios relating to screen readers. But doesn't conformity also require a visual indication?

Once again, styling off the aria-current attribute allows future team members, including yourself, to understand why the style is being applied, rather than a class name that may or may not be indicative. Because I'm using static examples, I've tied the Appendices link under references to match the current page.

Nested sublists are given extra left padding to visually indicate that they are related to and follow their controlling button.

Most of the styling is now completed. All that's left is to tweak the top-left and top-right borders with a border radius and shift the padding for a visual indication of child list items.

> ul {
  & > li > ul {
    & > li:first-child {
      &:has([aria-current="page"]) > a[href] {
        border-top-right-radius: calc(var(--sp-px) * 10);
      }
      & > button,
      & > a[href] {
        border-top-left-radius: calc(var(--sp-px) * 10);
      }
    }
  }

  & li {
    & button,
    & a[href] {
      padding-left: calc(var(--sp-px) * 16);
    }
  }
}

Focusable elements under the top row need their own styling. A faint line separates the elements, and while it disappears in a low-contrast emulation, the sufficient spacing between them compensates. The line stays stable regardless of colored vision deficiencies.

Am I the only one who finds using nested CSS and HTML selectors a lot easier than relying on classes?

Navigating With Tabs

ShaynaProductions — Tue, 09 Jun 2026 12:30:00 +0000

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 covered using an array of navigation objects to determine conditions and shift focus between components.

This article covers Tab Key navigation.

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.7.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 the useNavigation hook, 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.

You can view the requirements for the Tab Handling Keyboard Release along with previous requirements.

Introduction

As I've mentioned in earlier articles, keyboard handling has two disparate audiences: those who can see the screen and those who rely on a screen reader. The arrow, home and end keys, for the most part, rely on a user knowing where they are and being able to discern where they want to go when they choose a specific key; cursor movement needs to match the user's expectations of cursor movement on the screen.

While a screen reader user relies on the tab key to move around a browser window, those who perceive through the screen and operate a keyboard also use it to navigate components. The browser's default behavior for the Tab and Shift+Tab keys is to navigate the cursor through focusable elements in the order defined by the Document Object Model. Up until this point, the navigation component relied on the default behavior, which meant that using the Tab key caused the cursor to disappear as focus shifted to items not displayed on the screen.

For the most part, the up and down arrow key functionality added in the last release implements the functionality required by the Tab and Shift+Tab keys, making the acceptance criteria much easier to detail.

Acceptance Criteria - Tab Handling

Tab Key

AC 1 - With some exceptions, focus should match the arrow-down functionality. Link
AC 2 - If the link is part of the top row and is the last child, shift focus to the next focusable element outside of the component.
AC 3 - If the link is not part of the top row and is the last element within the component, shift focus to the next focusable element outside of the component.
AC 4 - If the link is not part of the top row, but is the last element associated with the parent on the top row, shift focus to the parent's next sibling. Button
AC 5 - If the sublist is not open and the button is the last child in its current list, shift focus to the next focusable item, based on the last link in its sublist's downline.

Shift + Tab Key

AC 6 - With some exceptions, focus should match the arrow-up functionality. Link
AC 7 - If the focusable element is the first child of the top list, focus should shift to the previous focusable element outside the component.
AC 8 - If the focusable element is the first child of the top list, focus should shift to the previous focusable element outside the component.

Users, through experience, have come to expect that the Tab and Shift+Tab keys are the only keys that move into and out of components. Additionally, when the tab key is pressed on the last visible element of an open list, focus should move to the parent's sibling instead of the default behavior of arrow-down, which shifts focus to the parent. Once again, work needs to be done to meet users' expectations.

Tab Key Handling

The tab key moves focus down the Document Object Model, landing only on focusable items. Focusable elements include form inputs, select, textarea, buttons and links. Other elements may be made focusable by setting tabindex="0" on an element; this should be used sparingly, if at all. In the navigation component, the focusable elements are the buttons and links.

Link

Implementing the Tab key begins by updating the handleKeyDown function in the components that hold the link and the button.

NavigationItem

const handleKeyDown = (e: React.KeyboardEvent) => {
    const linkEl = linkRef.current;

    switch (e.key) {
        case Keys.HOME:
        …
        case Keys.TAB:
            e.preventDefault();
            e.stopPropagation();
            break;
    }

    HandleCommonKeyDown(…);

    let focusableEl;
    switch (e.key) {
        …
        case Keys.TAB:
            if (e.shiftKey) {
                focusableEl = getPreviousByTabLink(linkEl);
            } else {
                focusableEl = getNextByTabLink(linkEl);
            }
            break;
    }
    if (focusableEl) {
        shiftFocus(focusableEl);
    }
};

GitHub (release 0.7.0) - NavigationItem.tsx - Line 109

Tab and Shift+Tab need to be handled in the same case statement, using the shiftkey prop to decide which controller function to call. In this case, getNextByTabLink() is available in the useNavigation hook.

useNavigation

AC 1

With some exceptions, focus should match the arrow-down functionality.

AC 2

If the link is in the top row and is the last child, shift focus to the next focusable element outside the component.

AC 3

If the link is not part of the top row and is the last element within the component, shift focus to the next focusable element outside of the component.

AC 4

If the link is not part of the top row, but is the last element associated with the parent on the top row, shift focus to the parent's next sibling.

const getNextByTabLink = ( linkEl ) => {
    let focusableEl = getNextByLink(linkEl);

    const isInTopRow = _isElementInTopRow(linkEl);

    if (
        (isInTopRow && !focusableEl) ||
        (!isInTopRow && _getLastElementInTopList(linkEl))
    ) {
        focusableEl = getFocusableElementFromDOM(
            linkEl,
            "next",
        ) as FocusableElementType;
    }

    return focusableEl;
};

GitHub (release 0.7.0) - useNavigation.tsx - getNextByTabLink Line 228

The first acceptance criterion states that most functionality should match the behavior when the arrow-down key is pressed on a link, so the first call to set the focusable element is made by calling getNextByLink.

The criteria covered by AC 2 and AC 3 have the same outcome; shifting focus to the first focusable element outside the component by calling a new utility function.

getFocusableElementFromDOM

export function getFocusableElementFromDOM(lastEl, direction) {
    //add all elements we want to include in our selection
    const focusable =
        'a:not([aria-disabled]), button:not([aria-disabled]), input[type=text]:not([aria-disabled]), select:not([aria-disabled]), textarea:not([aria-disabled]), [tabindex]:not([disabled]):not([tabindex="-1"])';

    const focusableElements = document.querySelectorAll(focusable);

    let index = -1,
        nextIndex;
    for (let i = 0; i < focusableElements.length; i += 1) {
        if (focusableElements[i] === lastEl) {
            index = i;
            break;
        }
    }
    if (direction === "next") {
        nextIndex = index + 1;
    } else {
        nextIndex = index - 1;
    }

    return focusableElements[nextIndex];
}

GitHub (release 0.7.0) - getFocusableElementFromDOM.ts

This utility function applies a document query selector to return a NodeList of all non-disabled focusable elements. Recall that in a previous article on updating accessibility within base components, there are issues using the disabled attribute within focusable elements, and as I demonstrated in the base/button component, the aria-disabled attribute was added when an element is disabled. The focusable variable uses aria-disabled to determine which elements to exclude from the list. If your code still uses disabled, then :not[disabled] should be added to the string.

Even though a NodeList provides index-based access like an array, it is not an array, and so no array-specific methods may be used. Specific to the direction, the index is incremented or decremented, and the appropriate next or previous focusable element is returned.

Button

AC 5

If the sublist is not open and the button is the last child in its current list, shift focus to the next focusable item, based on the last link in its sublist's downline.

Tabbing on a button differs from arrowing down on a button only by one criterion. When a button's sublist is not open, and the button is the last visible element in a list, shift focus to the next focusable element in the DOM.

SubNavigation.tsx

 const handleKeyDown = (e) => {
    const buttonEl = buttonRef.current;

    switch (e.key) {
        case Keys.HOME:
        …
        case Keys.TAB:
            e.preventDefault();
            e.stopPropagation();
            break;
    }

    HandleCommonKeyDown(…);

    let focusableEl: FocusableElementType | undefined;
    switch (e.key) {
        …
        case Keys.TAB:
            if (e.shiftKey) {
                focusableEl = getPreviousByTabButton(buttonEl);
            } else {
                focusableEl = getNextByTabButton(buttonEl);
            }
            break;
    }
    if (focusableEl) {
        shiftFocus(focusableEl);
    }
};

GitHub (release 0.7.0) - SubNavigation.tsx Line 146

Setting up the call for a Tab or Shift+Tab on a button requires the same basic code as in the NavigationItem component: calling the getNextByTabButton function.

useNavigation

getNextByTabButton

const getNextByTabButton = (buttonEl, isSubListOpen) => {
    let focusableEl = getNextByButton(buttonEl, isSubListOpen);

    const { storedList } = _getNavigationObjectByListElement(buttonEl);

    if (
        !isSubListOpen &&
        storedList.indexOf(buttonEl) === storedList.length - 1
    ) {
        const lastEl = _getLastElementByParent(buttonEl);

        focusableEl = getFocusableElementFromDOM(
            lastEl,
            "next",
        ) as FocusableElementType;
    }

    return focusableEl;
};

GitHub (release 0.7.0) - useNavigation.tsx - getNextByTabButton Line 205

As with the earlier getNextByTabLink function, focus is first set to whatever was returned when arrow-down is used, by calling getNextByButton first. The cascade replaces the focusable element only when the sublist is closed, and the button is the last element in its list. If the condition exists, then the last element under the top row parent, getLastElementByParent(), is returned, and the focusable element is the next focusable element in the DOM. This next focusable element may be in the component or outside of it, depending on which list the original button element is in.

const _getLastElementByParent = (parentEl) => {
    return _getRecursiveLastElementByParent(
        parentEl,
        _getNavigationObjectByListElement,
        _getNavigationObjectByParent,
    );
};

GitHub (release 0.7.0) - useNavigation.tsx - getLastElementByParent Line 71

As with the recursive function to find the ultimate ancestor of an element in the list, another recursive function is defined outside of the render, and the variables and functions necessary for the recursive function are passed through to accomplish its objective, returning the last focusable element of its descendants.

_getRecursiveLastElementByParent

export const _getRecursiveLastElementByParent = (
    focusableEl,
    _getNavigationObjectByListElement,
    _getNavigationObjectByParent,
) => {
    if (focusableEl.type === "button") {
        const { storedList } = _getNavigationObjectByParent(focusableEl);
        return _getRecursiveLastElementByParent(
            storedList[storedList.length - 1],
            _getNavigationObjectByListElement,
            _getNavigationObjectByParent,
        );
    } else {
        const { storedList } = _getNavigationObjectByListElement(focusableEl);
        return storedList[storedList.length - 1];
    }
};

GitHub (release 0.7.0) - hookFunctions.ts - _getRecursiveLastElementByParent

The element will always return the last item in a list when the element is a link, since a link is always the last element in any list. Recursion occurs when the passed-through element is a button, meaning the last element in its sublist must be retrieved and passed to the same function.

Shift+ Tab Key Handling

The Shift+Tab key combination handles movement to focusable elements above the current focus. Since the handlers were shown earlier, the code for NavigationItem and SubNavigation is not duplicated here.

AC 6

With some exceptions, focus should match the arrow-up functionality. ### AC 7
If the previous focusable item is a button and its sublist is open, focus should shift to the last child in the open sublist. ### AC 8
If the focusable element is the first child of the top list, focus should shift to the previous focusable element outside the component.

All three criteria are applied to the functionality for both links and buttons.

Link

useNavigation

getPreviousByTabLink

const getPreviousByTabLink =
    (linkEl) => {
        let focusableEl = getPreviousByLink(linkEl);
        if (_isElementInTopRow(linkEl)) {
            const { storedList } = _getNavigationObjectByListElement(linkEl);

            if (storedList.indexOf(linkEl) === 0) {
                focusableEl = getFocusableElementFromDOM(
                    linkEl,
                    "prev",
                ) as FocusableElementType;
            } else {
                focusableEl = _getPreviousElementInList(linkEl, storedList);
            }
        }
        return focusableEl;
    };

GitHub (release 0.7.0) - useNavigation.tsx - getPreviousByTabLink Line 288

AC 6 and 7 are covered with the getPreviousByLink functionality. The only difference between the two is that, when the element is the first child of the first row, it must find the previous focusable element outside the component.

Button

useNavigation

getPreviousByTabButton

const getPreviousByTabButton = (buttonEl) => {
    let focusableEl = getPreviousByButton(buttonEl);
    if (_isElementInTopRow(buttonEl)) {
        const { storedList } = _getNavigationObjectByListElement(buttonEl);
        if (storedList.indexOf(buttonEl) === 0) {
            focusableEl = getFocusableElementFromDOM(
                buttonEl,
                "prev",
            ) as FocusableElementType;
        }
    }
    return focusableEl;
};

GitHub (release 0.7.0) - useNavigation.tsx - getPreviousByTabButton Line 273

The getPrevious button and link controllers behave similarly: when the function handling the up-arrow is called, they retrieve the focusable element, and if the element is the first element in the top row, they shift focus to the first element in the DOM preceding the component.

Summary

The cascade pattern allowed us to leverage all the work done in the up/down keyboard-handling release, making it easy to handle tab key calls and focus solely on implementing the specific requirements unique to Tab and Shift+Tab.

Keyboard handling has been implemented for the most part. From an operable standpoint, all that's left is handling closing scenarios and tweaking the component for display and operability on mobile devices.

You can view how the implemented code works in this video.

My next article in the series will focus on working with color as I style a horizontal navigation component.

The Ups and Downs of Keyboard Handling

ShaynaProductions — Thu, 04 Jun 2026 12:15:00 +0000

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 covered creating the underlying data structures for supporting keyboard handling between components.

This article discusses implementing the up and down arrow keys to move focus between components.

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.6.0.

You can view the requirements for the Up/Down Keyboarding Release along with previous requirements.

This article is long and contains code and explanations. The code for this release is displayed, and the corresponding GitHub source is linked. Use these anchor links to return to the discussions of the individual components. Acceptance criteria are linked to the first component responsible for their implementation.

Content Links

Introduction
Acceptance Criteria
Preparation
- NavigationProvider
Down Arrow Handling
- Links
  - NavigationItem
  - useNavigation
- Buttons
  - SubNavigation
  - useNavigation
UpArrow Handling
- Links
  - NavigationItem
  - useNavigation
- Buttons
  - SubNavigation
  - useNavigation

Introduction

Most keyboard handling within components is fairly simple to implement. A key is pressed, and a function is called, which triggers an action. When implementing keyboard handling that requires shifting focus between components with complex conditional criteria, simplicity goes out the window. The fact is, the individual links and buttons within the navigation component have no way of knowing anything about any other links, buttons or lists. To handle shifting focus, the entire set of lists and sublists is duplicated into an array of objects to facilitate smooth keyboard handling.

A demonstration of the implemented keyboard handling is provided.

Acceptance Criteria

DOWN Key
All Focusable Items

AC 1 - Focus should move to the next focusable item in the same list.

When the currently focused item is a link:

AC 2 - If the link is the last child in its list and the link's parent is in the top row, shift focus to the parent.
AC 3 - If the link is the last element in its list and its' parent is the last element in its list, shift focus to the topmost parent in the top row.
AC 4 - If the focused link is the last child on the top row, focus remains on the link.
AC 5 - If the focused link is the last child in its list and its parent is not the last element in its list, shift focus to the parent's next sibling.

When the currently focused item is a button.

AC 6 - If the focused button's associated list is open, shift focus to the list's first child.
AC 7 - If the focused button's associated list is closed, and it is the last element in its list, shift focus to the button's ancestor in the top row.

UP Key
All Focusable Items

AC 8 - Focus should move to the previous element in the same list.
AC 9 - If the focused element is the first child on the top row, focus should remain on the focused element.
AC 10 - If the previous element in the list is a button and the sublist is open, shift focus to the parent's last child in the open sublist.

Requirements exist for both the Down and Up keys, which differ depending on whether the focused item is a link or a button and on its position in the current list/array. Conditionals in this case can become complex, hard to read and even harder to maintain. The rest of this article goes through the code.

Are you ready?

Return to Content Links

Preparation

The NavigationProvider stores the navigationArray of objects, each corresponding to a NavigationList component and its children. While code has been implemented to register the individual objects, there's been no way to retrieve the data until now.

NavigationProvider

export function NavigationProvider({...}) {
  ...

  const setListItems = ...

  const getNavigationArray =  useCallback(() => {
      return state.navigationArray;
    }, [state.navigationArray]);

  ...

  return (
    <NavigationContext.Provider
      value={{
        getNavigationArray,
        ...
getNavigationArray,
      }}
    >
      {children}
    </NavigationContext.Provider>
  );
}

GitHub (release 0.6.0) - NavigationProvider.tsx

A new provider function, getNavigationArray, is created and passed to the navigation hook for use, returning the entire navigation array stored in the state.

Down Arrow Handling

When keyboard handling is the focus, it's important to remember that there are two distinct classes with different expectations as to how a keyboard should work for them. Keyboard handling for someone who depends on a screen reader differs from that required for someone who depends on a screen for perceivability. Use of the arrow keys is restricted in some screen readers to specific situations, and many of them do not allow it outside those situations. Arrow key functionality is mainly used by those who use the screen/keyboard combination.

Because those who will use the arrow keys can view focus changes, the movement of these keys must correspond to common expectations for the keys themselves; a down arrow should move to the next currently visible focusable element on the screen, while an up arrow should shift focus to the previous currently visible focusable element. Keep in mind the movement will change depending on which element currently has focus, as well as its placement index within the navigationObject's storedList.

Links

I want to start by implementing the down arrow functionality on a link.

NavigationItem

export default function NavigationItem({...}){
  const { ..., shiftFocus} = useNavigationList();

  const { getNextByLink, registerItemInNavigationArray } = useNavigation();

  ...

  const handleKeyDown = (e) => {
    const linkEl = linkRef.current as HTMLAnchorElement;
    ...

    HandleCommonKeyDown(...);

    let focusableEl;
    switch (e.key) {
      case Keys.DOWN:
        focusableEl = getNextByLink(linkEl);
        break;
    }
    if (focusableEl) {
      shiftFocus(focusableEl);
    }
  };

  ...
}

GitHub (release 0.6.0) - NavigationItem.tsx Line 100

A new switch is added to handleKeyDown(), which calls the function getNextByLink provided by the useNavigation hook when the down arrow key is pressed. Rather than calling shiftFocus for each call, a mutable variable is redefined based on the key pressed, triggering a cascade that updates the focusableEl variable for the key that was handled.

The shiftFocus function is called only when a focusable element is returned, since there are times when focus should remain on the current element, and returning undefined will make this easier.

useNavigation

The getNextByLink and other variations discussed later can be thought of as controllers. They define the conditions and request the return of specific focusable elements to the keyboard handler. The conditions for returning the next focusable item after a link are specified in the acceptance criteria listed below.

AC 1

Focus should move to the next focusable item in the same list.

AC 2

If the link is the last child in its list and the link's parent is in the top row, shift focus to the parent.

AC 3

If the link is the last element in its list and its parent is the last element in its list, shift focus to the topmost parent in the top row.

AC 4

If the focused link is the last child on the top row, focus remains on the link.

AC 5

If the focused link is the last child in its list and its parent is not the last element in its list, shift focus to the parent's next sibling.

When the acceptance criteria are examined, it's clear that most of the conditional functionality occurs only when the link is the last child in its list. In any other scenario, focus moves to the next sibling.

getNextByLink

const getNextByLink = (linkEl) => {
  const { storedParentEl, storedList } = _getNavigationObjectByListElement(linkEl);

  // default to next item in list
  let focusableEl = _getNextElementInList(linkEl, storedList);

  // is Link the last element in the current list and not in the top row?
  if (
    storedList.indexOf(linkEl) === storedList.length - 1 &&  storedParentEl !== null
  ) {
    const isLinkLast = _isLastElementInCurrentList(linkEl);
    const isParentInTopRow = _isElementInTopRow(storedParentEl);
    const isParentLast = _isLastElementInCurrentList(storedParentEl);

    if (isParentInTopRow) {
      focusableEl = storedParentEl;
    } else if (isParentLast && isLinkLast) {
      focusableEl = _getTopRowElement(linkEl);
    } else {
      // focus goes to the parent's next sibling
      const parentNavObject =
        _getNavigationObjectByListElement(storedParentEl);
      const { storedList: parentList } = parentNavObject;
      focusableEl = _getNextElementInList(storedParentEl, parentList);
    }
  }

  return focusableEl;
};

GitHub (release 0.6.0) - useNavigation.tsx - getNextByLink - Line 149

Creating a set of conditionals that match each acceptance criterion one-to-one results in an unmitigated mess of unmaintainable, hard-to-debug, and unreadable code. I found it much easier to set a mutable variable and arrange the code so that the most common scenario is called first and sets the variable. Only when other conditions are met would the variable become overwritten. The result is easier to read and to maintain.

In this case, the most common scenario is simply moving to the next item in the list, but before that can happen, the navigation object containing the current link in the stored list must be returned.

Conditions are met as follows:

AC 1 - let focusableEl = _getNextElementInList(linkEl, storedList);`
AC 2 - if(isParentInTopRow){focusableEl = storedParentEl}`
AC 3 - if (isParentLast && isLinkLast) { focusableEl = _getTopRowElement(linkEl);}`
AC 5 - }else{.. const { storedList: parentList } = parentNavObject; focusableEl = _getNextElementInList(storedParentEl, parentList);`

You'll note that AC 4 isn't in the conditions to be handled. If focus should remain on the currently focusable element, the focusableEl will be undefined.

Outside of the controllers, all functions within the hook query the data store held in the context provider and return either boolean values to answer questions (isLinkLast, isParentInTopRow) or retrieve either a navigation object from the array or a focusable element to return to the calling component.

If your eyes glaze over at lots of code, you can skip down to the discussions around buttons.

_getNavigationObjectByListElement()

Navigation objects, each representing one list in the array, may be retrieved from the controller. In this case, a link may only appear within a storedList array, and so the link requests the object it is a part of:

const _getNavigationObjectByListElement = useCallback(
    (focusedEl) => {
      return getNavigationArray().find(({ storedList }) =>
        storedList.includes(focusedEl),
      );
    },
    [getNavigationArray]);

GitHub (release 0.6.0) - useNavigation.tsx - _getNavigationObjectByListElement - Line 28

Any focusable element, button or link will be exclusively contained in a navigation object's stored list array. Any function that calls the provider's getNavigationArray should be wrapped in a useCallback hook.

_getNextByLink()

  // default to next item in list
  let focusableEl = _getNextElementInList(linkEl, storedList);

const _getNextElementInList = (focusedEl, currentList) => {
    const nextIndex = currentList.indexOf(focusedEl) + 1;
    return currentList[nextIndex];
  };

GitHub (release 0.6.0) - useNavigation.tsx - _getNextElementInList() - Line 93

Unless a link is the last element in its list, the default requirement is to retrieve the next item. This function mimics the right-arrow key handling in the other context provider, NavigationListProvider, with one exception: regardless of whether the item is at the end of the list, the focus always moves to the next index, which can be outside the list length and so result in an undefined value. This corresponds to AC 4 - If the focused link is the last child on the top row, focus remains on the link. As mentioned earlier, a value of undefined is a valid return value.

getNextByLink()

if (
    storedList.indexOf(linkEl) === storedList.length - 1 &&  storedParentEl !== null
  ) {
    const isLinkLast = _isLastElementInCurrentList(linkEl);
    const isParentInTopRow = _isElementInTopRow(storedParentEl);
    const isParentLast = _isLastElementInCurrentList(storedParentEl);

GitHub (release 0.6.0) - useNavigation.tsx - getNextByLink - Line 157

Returning to the getNextByLink controller, every other aspect of the cascade requires the item not to be in the top row (storedParentEl !== null) and to be the last child in its list (storedList.indexOf(linkEl) === storedList.length - 1).

When the conditions are met, a series of questions is asked to determine the next steps.

The first question asks if the currently focused element is the last child in its list, while the last question asks the same of the current list's parent.

_isLastElementInCurrentList

const _isLastElementInCurrentList = (focusedEl) => {
    const { storedList } = _getNavigationObjectByListElement(focusedEl);
    return storedList.indexOf(focusedEl) === storedList.length - 1;
  };

GitHub (release 0.6.0) - useNavigation.tsx - _isLastElementInCurrentList - Line 87

_isElementInTopRow

const _isElementInTopRow = ( focusedEl ) => {
  return _getIndexInTopRow(focusedEl) >= 0;
};

const _getIndexInTopRow = useCallback((focusedEl) => {
      const { storedList } = getNavigationArray()[0];
      return storedList.indexOf(focusedEl);
    },
    [getNavigationArray],
  );

GitHub (release 0.6.0) - useNavigation.tsx - _isElementInTopRow - Line 65

The question of whether the passed-in element is part of the top row is answered by calling a function to extract the top-row object (which will always have an index of 0 since it was created as the first element when the navigation context provider was initiated). The top-row array is then checked to see whether the focused element is part of it.

The retrieved answers will help determine the remaining conditional requirements.

getNextByLink()

if (isParentInTopRow) {
      focusableEl = storedParentEl;
    } else if (isParentLast && isLinkLast) {
      focusableEl = _getTopRowElement(linkEl);
    } else {
      // focus goes to the parent's next sibling
      const parentNavObject =
        _getNavigationObjectByListElement(storedParentEl);
      const { storedList: parentList } = parentNavObject;
      focusableEl = _getNextElementInList(storedParentEl, parentList);
    }

GitHub (release 0.6.0) - useNavigation.tsx - getNextByLink - Line 165

The rest of the controller conditions depend on whether the parent is in the top row. If it is and the child is the last element in its list, then focus is shifted to the parent on the top row.

If both the parent and link are the last elements in their respective lists, focus shifts to the ancestor button in the top row, which can be found by calling the current element's top-row ancestor.

_getTopRowElement

const _getTopRowElement = (focusedEl) => {
  return _getRecursiveTopElementByElement(
    focusedEl,
    _getNavigationObjectByListElement,
    _isElementInTopRow,
  );
};

GitHub (release 0.6.0) - useNavigation.tsx _getTopRowElement - Line 71

Depending on an element's placement within the navigation component's sub-lists, finding the top row ancestor may require traversing multiple objects, so a recursive function is needed. Recursion shouldn't be used in the hook, since constant rendering can cause instability. Instead, a recursive function is created outside of the hook and called within. Variables passed through include the element and functions defined within the hook, which are necessary for its use.

_getRecursiveTopElementByElement

export const _getRecursiveTopElementByElement = (
  focusableEl,
  _getNavigationObjectByListElement,
  isElementInTopRow,
) => {
  const { storedParentEl } = _getNavigationObjectByListElement(focusableEl);

  if (isElementInTopRow(storedParentEl)) {
    return storedParentEl;
  } else {
    return _getRecursiveTopElementByElement(
      storedParentEl,
      _getNavigationObjectByListElement,
      isElementInTopRow,
    );
  }
};

GitHub (release 0.6.0) - hookFunctions.ts - _getRecursiveTopElementByElement

Recursive functions work well in scenarios with nested sublists. But there are constraints to using them in React when they are a part of the render. Instead of executing the recursion within the hook function itself, data and the required hook functions are passed to a common function residing outside of the component or hook. While they can be defined above the function in which they are called, they can also be stored in a separate file.

The recursive function first asks if the parent of the passed-through element, focusableEl, is in the top row. If so, the parent is returned. If the parent found is not in the top row, it is passed to the same function, and the process repeats until the parent on the top row is found and returned.

getNextByLink()

if (isParentInTopRow) {
      …
    } else if (isParentLast && isLinkLast) {
      …
    } else {
      // focus goes to the parent's next sibling
      const parentNavObject =
        _getNavigationObjectByListElement(storedParentEl);
      const { storedList: parentList } = parentNavObject;
      focusableEl = _getNextElementInList(storedParentEl, parentList);
    }

GitHub (release 0.6.0) - useNavigation.tsx - getNextByLink - Line 169

The last conditional happens when a link is the last child in its list, but its parent is not the last element in its own list. In that case, the focus shifts to the parent's next sibling via a call to _getNextElementInList(), passing both the parent and the list it belongs to.

With the down arrow on the link implemented, our focus (pun intended) shifts to the button.

Buttons

While a button can act like a focusable element when it is part of a list array, it also controls its own list. Shifting focus from a button depends on whether its list is open or closed when the down arrow key is pressed.

SubNavigation

export default function SubNavigation({...}){
  ...

  const handleKeyDown = (e) => {
    const buttonEl = buttonRef.current;

    ...

    let focusableEl;
    switch (e.key) {
      case Keys.DOWN:
        focusableEl = getNextByButton(buttonEl, isSubListOpen);
        break;
    }
    if (focusableEl) {
      shiftFocus(focusableEl);
    }
  };
  ...
}

GitHub (release 0.6.0) - SubNavigation.tsx Line 140

Just like the keydown handler for a link, a new controller, getNextByButton, is called, passing both the button element and the visibility of its sublist.

useNavigation

AC 1
Focus should move to the next focusable item in the same list

AC 6

If the focused button's associated list is open, shift focus to the list's first child.

AC 7

If the focused button's associated list is closed, and it is the last element in its list, shift focus to the button's ancestor in the top row.

Both links and buttons share the common criterion that the focus should move to the next focusable item in the same list. As for the rest, if the list associated with the button is open, then pressing the down key should shift focus to the first child in the open sublist. If the sublist is closed and the button is the last element of the entire list, then focus should be shifted to the ancestor on the top row.

GetNextByButton

const getNextByButton = (buttonEl, isSubListOpen) => {
  const { storedList: currentList } =
    _getNavigationObjectByListElement(buttonEl);
  // default to next item in list
  let focusableEl = _getNextElementInList(buttonEl, currentList);

  if (isSubListOpen) {
    const currentNavObject = _getNavigationObjectByParent(buttonEl);
    const { storedList: subNavigationList } = currentNavObject;
    // move to the sublist's first child
    focusableEl = subNavigationList[0];
  } else if (currentList.indexOf(buttonEl) === currentList.length - 1) {
    // last focusable element and sublist is collapsed. Set to parent;
    focusableEl = _getParentByElement(buttonEl) as FocusableElementType;
  }

  return focusableEl;
};

GitHub (release 0.6.0) - useNavigation.tsx - GetNextByButton - Line 126

Both buttons and links first call _getNextElementInlist. Just as with links, any button finding itself at the end of its list will return undefined.

Everything else depends on whether the sublist controlled by the button is open.

If the sublist is open, focus should shift to the controlled list's first element, contained at index 0.

If you skipped over the code explanations for link handling, you might want to skip down to the discussions around up arrow handling.

To reach into the controlled list to find the first element, an object must be retrieved by the parentElement.

_getNavigationObjectByParent

const _getNavigationObjectByParent = useCallback((parentEl) => {
      return getNavigationArray().find(
        ({ storedParentEl }) => storedParentEl === parentEl,
      );
    },
    [getNavigationArray],
  );

GitHub (release 0.6.0) - useNavigation.tsx - _getNavigationObjectByParent - Line 38

The object is returned when the storedParent matches the parent element passed in.

If the button is at the end of a list and its controlled sublist is closed, the topParent is retrieved, as discussed in the getNextByLink controller.

Down arrow handling is complete.

Up Arrow Handling

When using the up arrow, the visible focus should move up smoothly through any visible list items. If the currently focused element is the first child in an open list, then focus should shift onto the controlling button. If the currently focused element's previous sibling is a button, handling depends on the previous sibling's list-open status. If the list is open, focus should shift to the last child in the open list. If it is closed, then focus should shift to the element's previous sibling.

Links

NavigationItem

export default function NavigationItem({...}){
  const { ..., shiftFocus} = useNavigationList();

  const { getNextByLink, registerItemInNavigationArray } = useNavigation();

  ...

  const handleKeyDown = (e) => {
    const linkEl = linkRef.current as HTMLAnchorElement;
    ...

    HandleCommonKeyDown(...);

    let focusableEl;
    switch (e.key) {
      case Keys.UP:
        focusableEl = getPreviousByLink(linkEl);
        break;
       ...
    }
    if (focusableEl) {
      shiftFocus(focusableEl);
    }
  };

  ...
}

GitHub (release 0.6.0) - NavigationItem.tsx

Another controller, getPreviousByLink, is called in the component when the up arrow key is pressed.

useNavigation

The called controller calls and sets up the conditionals to meet the last three acceptance criteria.

AC 8

Focus should move to the previous element in the same list.

AC 9

If the focused element is the first child on the top row, focus should remain on it.

AC 10

If the previous element in the list is a button and the sublist is open, shift focus to the parent's last child in the open sublist.

const getPreviousByLink = ( linkEl) => {
  const isButton = (focusableEl) => {
    return focusableEl?.type === "button";
  };

  let focusableEl = _getPreviousByElement(linkEl);
  if (isButton(focusableEl)) {
    const { isSubListOpen, storedList } = _getNavigationObjectByParent( focusableEl  );
    if (isSubListOpen && storedList.indexOf(linkEl) < 0) {
      focusableEl = storedList[storedList.length - 1];
    }
  }
  return focusableEl;
};

GitHub (release 0.6.0) - useNavigation.tsx - getPreviousByLink - Line 187

Compared to all the requirements in getNextByLink(), getPreviousByLink() is much simpler. That's because most of the complexity is shared with its button counterpart and is therefore placed in the _getPreviousByElement function. Once an element is returned, it must be checked whether it is a button, since the last acceptance criterion, AC 10, requires this determination.

To determine the element type, a tagname (which is available in any HTML element; in this case, "BUTTON") could be used. A button element also has a "type" attribute that specifies either "submit" or "button," which is what I have chosen to use.

When the focusable element returned by _getPreviousByElement() is a button, and the list it controls is open, then the button's children must be checked to determine whether the link is part of the list. If it isn't, the focus shifts to the last child of the list controlled by the button.

_getPreviousByElement

const _getPreviousByElement = (focusedEl) => {
  const { storedList, storedParentEl } =
    _getNavigationObjectByListElement(focusedEl);

  // default to previous item in list
  let focusableEl = _getPreviousElementInList(focusedEl, storedList);

  const isInTopRow = _isElementInTopRow(focusedEl);

  // not on the top row and first child in its list.
  if (!isInTopRow && storedList.indexOf(focusedEl) === 0) {
    focusableEl = storedParentEl;
  }
  if (!isInTopRow || focusedEl !== _getFirstElementInIndexedList(0)) {
    return focusableEl;
  }
};

GitHub (release 0.6.0) - useNavigation.tsx - _getPreviousByElement - Line 105

In most cases, the focus shifts to the up arrow in the same way, whether it's a button or a link. As with the similar down-arrow functionality, the most common event is to shift focus to the previous sibling of the current list via the _getPreviousElementInList function.

The currently focused element is then checked to determine whether it is on the top row and the first child in its row. The button controlling the current list is only set to the focusable element if the element is not on the top row.

The last call returns the next element to focus on only if the currently focused element is not in the top row. If it is in the top row, the next focusable element is returned only if it isn't the first child in the array.

Two new functions are utilized in this function: _getPreviousElementInList and _getFirstElementInIndexedList.

_getPreviousElementInList

const _getPreviousElementInList = (focusedEl, currentList) => {
    const previousIndex = currentList.indexOf(focusedEl) - 1;
    return currentList[previousIndex];
  };

GitHub (release 0.6.0) - useNavigation.tsx - _getPreviousElementInList - Line 99

Like its _getNextElementInList counterpart, the call returns the element at the previous index in the array. If the element passed through is the first child, the returned element is undefined.

_getFirstElementInIndexedList

const _getFirstElementInIndexedList =  useCallback((index) => {
      return getNavigationArray()[index].storedList[0];
    },
    [getNavigationArray],
  );

GitHub (release 0.6.0) - useNavigation.tsx - _getFirstElementInIndexedList - Line 57

Like any other query function, calling getNavigationArray directly, _getFirstElementInIndexedList is wrapped in a useCallback hook. Since the top row is always at index 0 and the first element in the stored list is at index 0, the return is straightforward to write.

Buttons

Moving the focus backward from a button is the simplest function, since all of its dependencies have already been written.

SubNavigation

export default function SubNavigation({...}){
  ...

  const handleKeyDown = (e) => {
    const buttonEl = buttonRef.current;

    ...

    let focusableEl;
    switch (e.key) {
      case Keys.Up:
        focusableEl = getPreviousByButton(buttonEl);
        break;
    }
    if (focusableEl) {
      shiftFocus(focusableEl);
    }
  };
  ...
}

GitHub (release 0.6.0) - SubNavigation.tsx - Line 137

For a button, handling the up arrow key only requires passing the button element, not its sublist state.

useNavigation

getPreviousByButton

const getPreviousByButton = ( buttonEl) => {
  return _getPreviousByElement(buttonEl);
};

GitHub (release 0.6.0) - useNavigation.tsx - getPreviousByButton - Line 181

The button only depends on the focusable element returned by the shared _getPreviousByElement.

Summary

So far, this layer of progressive enhancements has been the most complex to implement. Keeping track of the conditions necessary for each element type and direction was made far simpler by having each focusable element cascade from the most to the least common. Up and Down keyboard handling has been achieved. You can try it yourself by downloading the release and running the examples.

Unlike the up and down arrow keys, Tab key handling is integral to both screen and screen reader, and I'll be handling that in the next release.

Laying it all out on the Vertical

ShaynaProductions — Tue, 02 Jun 2026 12:15:00 +0000

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 article, I covered creating the underlying data structures for supporting keyboard handling between components.

This article, along with its accompanying release, focuses on the design and styling of a navigation component whose first row is laid out vertically, consistent with mobile navigation.

Note: This article is one of a series demonstrating how to build 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 building on the previous, 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.5.2.

While code examples are written in JavaScript for brevity, all actual code is written in Typescript and targets React 19.x. Examples use Next.js 16.x, which is not required to run the navigation component.

Follow along either by downloading the release and running the examples while examining the codebase, or by activating the link accompanying each code snippet to view the full file on GitHub.

This article is fairly long. It contains code and explanations. The code for this release is displayed, and the corresponding GitHub source is linked. Use these anchor links to move to the items of interest.

Content Links

Introduction
Layout
- Top Row Layout
- SubList Layout
Focusable Element Standardization
Separators and Weights
Summary

Introduction

Earlier, I went through creating layouts for a navigation component suitable for desktop or laptop widths. This time, I want to focus on a layout for the same component that is suitable for mobile devices.

Between my insistence that all my flow-control elements (those that always begin on a new line when the default positioning of static is applied) default to no specific width of their own and my use of nested CSS to style, I'm finding it much easier to achieve layouts.

In my experience, the longer a website has existed, the more fragile its CSS becomes. Whether the CSS is styled in separate sheets or inside the components, it becomes a struggle to keep everything consistent. Multiple classes are chained together, and name-spaces are prepended onto them in an attempt to stop one style from stepping onto another. Styling within a component seems simpler, but is it really?

Structural HTML doesn't just help screen readers; it's also useful when styling the screen. There's something freeing about styling an entire component with a single class and using descendant and sibling selectors. Styles become easier to trace, and I'm no longer puzzling over which styles are targeted, a situation that tends to hinder debugging style issues, especially if a styling library is misconfigured and production-level obfuscation is applied in development. Add layer rules, ensure browser styling is consistent, and working with CSS becomes a smooth flow rather than a fight.

The selectors I used in the horizontal layout are still applicable to this vertical layout; the only differences are the initial class and the rules within the selectors. In this case, the top row will be vertically aligned rather than horizontally. The pattern is still one of disclosure, but it should follow the keyboard rules for an accordion rather than a menu.

Initially unstyled, the navigation component, while not yet polished, still reflects the basic shape I'm looking for. Thanks to the [data-orientation="vertical"] passed to the vertically aligned menu, the List component sets up the initial layout right away.

Spacing is a mess, buttons are ugly, and nothing really lines up. However, even with these issues, it's still operable and understandable.

Return to Content Links

Layout

Top Row Layout

Recall that everything in React eventually becomes plain old HTML, and the structure defined for the navigation output details the styling order in Nested CSS.

<nav>
    <ul>
        <li><a href="#" id="item-one">Item One</a></li>
        <li><a href="#" id="item-two">Item Two</a></li>
        <li>
            <button id="item-three">Item Three</button>
            <ul id="subnav-1">
                <li><a href="#" id="item-four">Item Four</a></li>
                <li><a href="#" id="item-five">Item Five</a></li>
                <li>
                    <button id="item-six">Item Six</button>
                    <ul>
                        <li><a href="#" id="item-seven">Item Seven</a></li>
                        <li><a href="#" id="item-eight">Item Eight</a></li>
                    </ul>
                </li>
            </ul>
        </li>
    </ul>
</nav>

HTML Structure, Top row targeted in the CSS.

@layer system-component {
  nav.vertical-navigation {
    /* Layout */
    padding: calc(var(--sp-px) * 16);

    /* Top Row nav > ul > li  */

    & > ul {
      & > li {
        & > button,
        & > a[href] {
          padding-left: 0;
          justify-content: flex-start;
        }
      }
    }
  }
}

GitHub (release 0.5.2) - styledVertical.css

Since the nav element has only one direct descendant, almost everything except padding is targeted by the unordered list's enclosing styles, which are directly contained within the nav element. Direct descendants always use a > and so anything contained within the direct unordered list will be styled accordingly, while nothing outside will be affected.

The styling in this bit only targets the top row through another direct descendant, & > li {} is set and then buttons and links that are direct descendants of the top row list items are set to justify the content within to a left alignment (flex-start), which overcomes the button's default alignment of center.

Return to Content Links

SubList Layout

The subnavigation lists and focusable elements are next.

& > ul {
… /* Top Row */
        & > ul {
          & li {
            width: 100%;
          }

          & > li {
            & button,
            & a[href] {
              flex-wrap: nowrap;
              justify-content: flex-start;
              padding: calc(var(--sp-px) * 16);
            }
          }

          & ul {
            & > li {
              padding-left: calc(var(--sp-px) * 16);
            }
          }
        }

Any unordered lists that are the direct descendants of the top row list items are then targeted. List items are given a width of 100% to help with the target size, and buttons and links that are direct descendants of the sub-lists are given some padding to visually distinguish them from the primary list, with the content left-aligned.

Styling based on elements, descendants and siblings maps CSS onto the structure, increasing readability and maintainability. It's easier to figure out where something is being applied, which makes fixes much easier.

Return to Content Links

Focusable Element Standardization


& li {
    & a[href]{
        display: inline-block;
    }
  & button,
  & a[href] {
    background-color: transparent;
    border-color: transparent;
    border-radius: 0;
    border-width: calc(var(--sp-px) * 2);
    color: var(--component-text-color);
      min-height: calc(var(--sp-px) * 16);
      padding-top: calc(var(--sp-px) * 4);
      padding-bottom: calc(var(--sp-px) * 4);
    width: 100%;
    text-align: left;
  }
}

Styling outside of components makes it easier to apply CSS consistently. Consider that buttons and links live in their own navigation components. Buttons are contained in the SubNavigation component while links live in the NavigationItem. When CSS is applied either via Tailwind classes or within the component itself, the styles need to be applied separately and maintained consistently. It's frustrating, and at some point, a developer may overlook that changes in one file require changes in another.

In this case, I can target buttons and links together to maintain consistency. Spacing is made consistent by setting the link element to display: inline-block, which allows width and a minimum height to be applied, along with some top and bottom padding.

Buttons and links are given a 100% width. By expanding the button's width to fill the entire list item, the target size increases, making it easier for someone using a pointer of any sort, mouse, finger or tracking device to actually interact with a particular button.

Removing the default background and border colors and standardizing the padding work wonders, moving the layout from ugly to more professional.

Return to Content Links

Separators and Weights

The font weights are inconsistent between the buttons and links, and some separation is needed to clarify the difference between the primary and subsequent lists.

& > ul {
  & li:has(button) {
    border-bottom-width: calc(var(--sp-px) * 2);
    border-bottom-color: var(--component-border-color);
    border-bottom-style: solid;
    padding: calc(var(--sp-px) * 4) inherit;

    &:has(button[aria-expanded="true"]) {
      border-bottom-color: transparent;
      & > button {
        border-bottom-color: var(--component-border-color);
      }
    }
  }

  & button,
  & a[href] {
    font-weight: 400;
  }

  & > ul {
    padding-top: calc(var(--sp-px) * 8);
  }
}

Have you ever wanted to style an element base on something it contains or an attribute a child element exposes? Modern CSS supports it through the :has pseudo-selector.

If the list item contains a button, it is given a bottom border that disappears when the button within it is expanded. When the button is expanded, the list border is set back to transparent and the bottom border moves to the button.

The :has () pseudo-selector allows for the application of a style to a parent element based on specific attributes of a child element. In this case, whether the button has exposed the attribute, aria-expanded="true". When it does, both the parent and the child can be styled together by moving the colored border from the bottom of the list to the bottom of the button.

&:has(button[aria-expanded="true"]) styles the list item when it has a button with the attribute aria-expanded="true". I prefer using existing attributes rather than creating new classes. It creates a more readable, understandable stylesheet and better details the required state than something applied as a class.

Return to Content Links

Summary

Testing with larger browser font sizes confirms proportions and ratios are consistent.

Structural HTML, Layers and Nested CSS are natural allies, creating an understandable, traceable and maintainable set of styles. The stylesheet can be stored alongside the component and configured to affect only the component itself.

In my next article in this series, I'll be implementing keyboard navigation using the up and down arrow keys to shift focus between components.

Are You My Parent?: Scaffolding in the architecture necessary for keyboard handling between components.

ShaynaProductions — Thu, 28 May 2026 12:15:00 +0000

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 article, I demonstrated how structural HTML and Nested CSS go hand in hand, allowing for readable, maintainable stylesheets as work progressed on the beginnings of a styled navigation component suitable for desktop.

This article and its release focus on setting up for future success by adding the underlying data handling needed to support shifting focus between lists and components.

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.5.2.

You can view the requirements for the Parent Provider Release along with previous requirements.

Follow along either by downloading the release and running the examples while examining the codebase, or by activating the link accompanying each code snippet to view the full file on GitHub.

Content Links

Introduction
Acceptance Criteria
Who is my Parent?
- NavigationListProvider
- useNavigationList
- NavigationList
Setting up the Navigation Provider
- NavigationProvider
- useNavigation
- Navigation
- NavigationItem
- SubNavigation
Summary

Introduction

There comes a point in developing a non-trivial component when handling data becomes a prime consideration, and this time has arrived in the navigation component.

Whether a link or a button, a focusable item residing in a list item is unaware of its siblings or anything about the list it is not part of. One list has no way of knowing what another list contains.

Keyboard handling for a single list was implemented using a context provider to hold an array of focusable elements associated with that list. It meant the current element holding focus could send a request to the hook associated with the context provider to shift focus from itself to another element in the same list without knowing anything else.

Thinking ahead to the functionality required to move between components using the up and down arrow keys, along with Tab, requires each element to be able to traverse a series of lists to find the correct item to shift focus or execute other situations, such as where to place focus when a user closes the component using the keyboard.

Whether a link or a button, each focusable item resides in an array held by the NavigationListProvider. A SubNavigation component holds the button that controls the sublist along the sublist itself, meaning each list can be associated with a parent and know whether its sublist is open.

A tree data structure where the button serves as the intermediary is the logical step, so the following acceptance criteria were determined.

Acceptance Criteria

AC-1 - Every focusable element should have access to the button controlling its list.
AC-2 - A navigation context provider should hold an array of navigation objects.
AC-3 - Each focusable element should register itself in the appropriate navigation object within the array.
AC-4 - Each subnavigation button should register itself in its own navigation object as the controlling element.

At the end, the object array should resolve to the following shape:

[
{   
    parentEl: null,
    isSublistOpen: true,
    subList: [Community, Tales, Reference, About]
},
{
    parentEl: Community,
    isSublistOpen: false,
    subList: [Musings, Forum]
},
{   
    parentEl: Tales
    isSublistOpen: false,
    subList: [Search, All Stories, All Commentary,  Find Your Next Story]
 },
{
    parentEl: Search, 
    isSubListOpen: false, 
    subList: [Basic Search, Advanced Search]
},
{
    parentEl: Find Your Next Story, 
    isSublistOpen: false, 
    subList: [By Storyteller, By Era]
},
{
    parentEl: Reference, 
    isSubListOpen: false, 
    subList: [Appendices, Characters, Glossary]
},
{
    parentEl: About, 
    isSublistOpen: false, 
    subList: [ About the Site, Contact Us, Privacy Policy, Accessibility, Donate,]
    }
]

Note that every button is listed twice, once in a sublist and as a parent element. The first list will always be the first object in the array.

Creating the underlying data structure and the functionality to register elements within it is the focus of this release.

Return to Content Links

Who is my Parent?

AC-1 - Every focusable element should have access to the button controlling its list.

As the current architecture stands, a button can control a list but has no information about its items. At the same time, no item within a list currently has any way of finding or focusing on anything outside its own list. The solution is for each item to know its parent and to access a data structure that returns the next focusable item.

Since the NavigationList component already has access to its parent and a provider, it should be fairly simple to extend it to hold a reference to its parent, which will be a button for any list held in the Subnavigation component, or null when the NavigationListProvider is initialized from the NavigationList component.

NavigationListProvider

 export function NavigationListProvider({ children, value }) {
    const { parentRef } = value;
    const [state, dispatch] = useReducer(navigationListReducer, {
        parentRef: parentRef,
        items: [],
    });

    const getCurrentListItems = ...;

    const getParentEl = useCallback(() => {
        return state.parentRef.current;
    }, [state.parentRef]);

    const registerItemInCurrentList = ...;

    return (
        <NavigationListContext.Provider
            value={{
                getCurrentListItems,
                getParentEl,
                registerItemInCurrentList,
            }}
        >
            {children}
        </NavigationListContext.Provider>
    );
}

GitHub (release 0.5.2) - NavigationListProvider.tsx

The parent reference joins the empty items array within the reducer's state. There's no need to dispatch a call to the reducer; simply returning the current property from the parentRef held in state is enough.

useNavigationList

export function useNavigationList() {
    const navigationListContextObj = use(NavigationListContext);
    const { getCurrentListItems, getParentEl, registerItemInCurrentList } =
        returnTrueElementOrUndefined(
            !!navigationListContextObj,
            navigationListContextObj,
        );

    const currentListItems = getCurrentListItems();
    const parentEl = getParentEl();

...

    return {
        currentListItems,
        parentEl,
        ...
    };
}

GitHub (release 0.5.2) - useNavigationList.tsx

The getParentEl function is passed through to the navigation list hook, which masks the get() as a variable, as a nicety and passes it through.

To guarantee data is fresh, provider functions must be called to retrieve any data held by the provider. Passing the data itself to the hook will never refresh it, and while that might be fine for a parent reference that never changes, other information retrieved needs to be up to date, so getParentEl is created for consistency.

NavigationList

export default function NavigationList({
    ...
        parentRef,
    ...rest
}){
    const listContext = {
        parentRef: parentRef,
    };
    const listProps = ...'

    return (
        <NavigationListProvider value={listContext}>
            <List key={`list-$id`} {...listProps}>
                {children}
            </List>
        </NavigationListProvider>
    );
}

GitHub (release 0.5.2) - Navigation.tsx

All that's necessary is to pass the parentRef into any NavigationList and send it to the context provider.

With a parentRef now available to any NavigationItem or SubNavigation component, I can now begin development on a new context provider to hold an array of objects, each representing a different list.

Return to Content Links

Setting up the Navigation Provider

AC-2 - A navigation context provider should hold an array of navigation objects.

A navigation component is composed of one or more lists, so an array of objects is appropriate. Each object should hold the parent element and another array containing the items in the specific list. Knowing whether a list is opened or closed is going to come in handy, so a navigation object's shape can be stated as an object:

navigationObject = {
storedParentEl, /* parentRef.current */
storedList, /* [] - an array of Focusable Elements (links and buttons) held in the list controlled by the parent */
ssSubListOpen /* boolean - reflects the current state of the stored list's visibility.  */
}

One object for each list held in the navigation component will be stored in the array. Each list will have access to its parent, and each item within the storedList will be able to ascertain the list's visible state.

It's time to insert a new context provider into the component.

NavigationProvider

A top-level context provider that wraps all the nested components that make up the lists displayed in the navigation component is required to hold all the returned data. When it's complete, the entire data structure for every link and navigation button will be stored in a reducer.

export function NavigationProvider({ children, value }) {
    const { data } = value;
    const navigationObject = {
        storedParentEl: data.storedParentEl,
        isSubListOpen: data.isSubListOpen,
        storedList: [],
    };

    const [state, dispatch] = useReducer(navigationReducer, {
        NavigationArray: [navigationObject],
    });

    const setIsListOpen = useCallback((isListOpen, parentEl) => {
        dispatch({ type: "SET_IS_LIST_OPEN", parentEl, isListOpen });
    }, []);

    const setListItems = useCallback((navigationList, parentEl) => {
        dispatch({
            type: "SET_LIST_ITEMS",
            parentEl,
            navigationList: navigationList,
        });
    }, []);

    const registerButtonAsParent =  (isListOpen, parentEl) => {
        dispatch({ type: "SET_PARENT", parentEl, isListOpen });
    };

    const registerItemInNavigationArray =  (navigationList, parentEl) => {
        setListItems(navigationList, parentEl);
    };

    return (
        <NavigationContext.Provider
            value={{
                registerButtonAsParent,
                registerItemInNavigationArray,
                setIsListOpen,
                setListItems,
            }}
        >
            {children}
        </NavigationContext.Provider>
    );
}

Since updates are interdependent and registration occurs across different components, a reducer is used again to enable more granular state management. By using a reducer, each dispatch is applied to the latest state, actions can be processed in order, and all transitions are immutable.

navigationReducer

export function navigationReducer(
    state,
    action,
){
    switch (action.type) {
        case "SET_PARENT": {
            const exists = state.navigationArray.some(
                (obj) => obj.storedParentEl === action.parentEl,
            );
            if (exists) return state;

            const navObj= {
                storedParentEl: action.parentEl,
                isSubListOpen: action.isListOpen,
                storedList: [],
            };

            return {
                ...state,
                navigationArray: [...state.navigationArray, navObj],
            };
        }

        case "SET_IS_LIST_OPEN": {
            const index = state.navigationArray.findIndex(
                (obj) => obj.storedParentEl === action.parentEl,
            );
            const current = state.navigationArray[index];
            if (current.isSubListOpen === action.isListOpen) return state;

            const next = state.navigationArray.slice();
            next[index] = { ...current, isSubListOpen: action.isListOpen };

            return { ...state, navigationArray: next };
        }

        case "SET_LIST_ITEMS": {
            const index = state.navigationArray.findIndex(
                (obj) => obj.storedParentEl === action.parentEl,
            );

            const current = state.navigationArray[index];
            const currentList = returnArray(current.storedList);
            const nextList = action.navigationList;

            if (arraysEqual(currentList, nextList)) return state;

            const next = state.navigationArray.slice();
            next[index] = { ...current, storedList: nextList };

            return { ...state, navigationArray: next };
        }

        default: {
            return state;
        }
    }
}

GitHub (release 0.5.2) - navigationReducer.ts

Reducers are typically handled as switch statements, based on their action types. Unlike setters derived from useState, reducers can rely on specific conditions to determine whether to update the reducer state they are responsible for.

SET_PARENT - checks for the existence of the passed-in parent element within the navigation array. If it doesn't exist, a new navigation object is created with the parent, an empty sublist, and whether the sublist is visible, and it is stored in the array.

SET_IS_LIST_OPEN - updates the boolean value on the object where the parent element matches the passed-through parent, only if the value has changed.

SET_LIST_ITEMS - updates the storedList within the object whose parent element matches the passed-through parent, only when the stored list doesn't match the list being passed through.

useNavigation

export function useNavigation() {
    const navigationContextObj = use(NavigationContext);
    const {
        registerItemInNavigationArray,
        registerButtonAsParent,
        setIsListOpen,
        setListItems,
    } = returnTrueElementOrUndefined(
        !!navigationContextObj,
        navigationContextObj,
    );

    return {
        registerItemInNavigationArray,
        registerButtonAsParent,
        setIsListOpen,
        setListItems,
    };
}

GitHub (release 0.5.2) - useNavigation.ts

The public functions are returned from the NavigationProvider and passed through by a new hook, useNavigation.

Navigation

The context provider needs to be established within the navigation component.

  export default function Navigation({ isOpen = true, ...}){
    const parentRef = useRef(null);

    const navigationProps = {...};

   const navigationContextProps = {
      data: {
        isSubListOpen: isOpen,
        storedParentEl: null,
        storedList: [],
      },
   };

const navigationListProps: NavigationListProps = {
        ...,
        parentRef,
    };

  return (
    <>
      <NavigationProvider value={navigationContextProps}>
        <nav {...navigationProps}>
          <NavigationList {...navigationListProps}>{children}</NavigationList>
        </nav>
      </NavigationProvider>
    </>
  );
}

GitHub (release 0.5.2) - Navigation.tsx.

When initializing the first object to be stored in the array, not much is known. There are no items in the list, and the parent element for the top row will always be null. All that is really known is whether the list is open, which, for a horizontally aligned, uncontrolled component, is always true.

A parentRef is provided to be passed through to the NavigationList component, and an initial object is formed, which will always be the first object in the array. The top-level list will never have a controlling element, and the storedList is always sent in as an empty array to be filled during the registration process. Every other list is rendered in the SubNavigation component, and so has a valid parent element: the button that controls it.

With the provider in place, it's time to register the information.

NavigationItem

AC-3 - Each focusable element should register itself in the appropriate navigation object within the array.

export default function NavigationItem({...}) {
    const {
        currentListItems,
        parentEl,
        ...
    } = useNavigationList();

    const { registerItemInNavigationArray } = useNavigation();
    const currentPath = ...;

    const linkRef = useRef(null);
    const prevCurrentListItems = usePrevious(currentListItems);

    useEffect(() => {
        if (linkRef.current !== null) {
            registerItemInCurrentList(linkRef.current);
        }
    }, [linkRef, registerItemInCurrentList]);

    useEffect(() => {
        const prevList = prevCurrentListItems || [];
        if (
            linkRef.current !== null &&
            currentListItems.length > 0 &&
            !arraysEqual(currentListItems, prevList)
        ) {
            registerItemInNavigationArray(currentListItems, parentEl);
        }
    }, [
        currentListItems,
        linkRef,
        parentEl,
        prevCurrentListItems,
        registerItemInNavigationArray,
    ]);

...
    return (
        <ListItem key={id} {...listItemProps}>
            <Link {...linkProps}>{label}</Link>
        </ListItem>
    );
}

GitHub (release 0.5.2) - NavigationItem.tsx

Within the NavigationItem component, a new useEffect hook is added that passes the currentItemsList and the parent element retrieved from the useNavigationList hook into the navigationArray held by the NavigationProvider.

Effectively, this useEffect should run the registration function only once under very specific conditions. The issue is that the first time this hook is called, the linkRef will return null because the link element hasn't yet been initialized and needs to run after initial rendering. Which means it will run when the dependency array changes. I can leverage React's batch updates and send over the list of focusable elements maintained by the navigation list context provider rather than continuously updating it.

A usePrevious hook retrieves the previous makeup of the currentListItems array, which is the single list array stored in the NavigationListProvider. The function that registers the item into the navigation array is only run when the link element is known and no longer null, and the list actually contains a non-empty array that does not match the previous list.

The same registration needs to be added to the SubNavigation component to register the button into the navigation array as a focusable element.

Subnavigation

AC-4 - Each subnavigation button should register itself in its own navigation object as the controlling element.

export default function SubNavigation({...}) {
    const {
        currentListItems,
        parentEl,
        ...
    } = useNavigationList();

    const {
        registerButtonAsParent,
        registerItemInNavigationArray,
        setIsListOpen,
    } = useNavigation();

    const buttonRef = useRef(null);
    const [buttonEl, setButtonEl] = useState(null);
    ...

    const closeSubNavigation = useCallback(() => {
        setIsListOpen(false, buttonEl);
        setIsSubListOpen(false);
    }, [buttonEl, setIsListOpen, setIsSubListOpen]);

    const openSubNavigation = useCallback(() => {
        setIsListOpen(true, buttonEl);
        setIsSubListOpen(true);
    }, [buttonEl, setIsListOpen, setIsSubListOpen]);

    useEffect(() => {
        if (buttonRef.current !== null) {
            registerItemInCurrentList(buttonRef.current);
            registerButtonAsParent(isSubListOpen, buttonRef.current);
        }
    }, [
        buttonRef,
        isSubListOpen,
        registerButtonAsParent,
        registerItemInCurrentList,
    ]);

    useEffect(() => {
        const prevList = prevCurrentListItems || [];
        if (
            buttonRef.current !== null &&
            currentListItems.length > 0 &&
            !arraysEqual(currentListItems, prevList)
        ) {
            registerItemInNavigationArray(currentListItems, parentEl);
        }
    }, [
        currentListItems,
        parentEl,
        prevCurrentListItems,
        registerItemInNavigationArray,
    ]);

...

    const handlePress = () => {
        if (isSubListOpen) {
            closeSubNavigation();
        } else {
            openSubNavigation();
        }
    };

    ...

    const navigationListProps: NavigationListProps = {
        ...
            parentRef: buttonRef,
        ...
};
    return (  ...  );
}

GitHub (release 0.5.2) - Subnavigation.tsx

The handlePress function is refactored to call a function based on the current sublist's visibility, rather than toggling its open state. Both the sublist visibility held in the component's state and the call to update the object in the NavigationProvider's reducer are set to true or false in the same function.

When the button element has been rendered, not only is it registered in the current list, but the button is registered as a parent within the navigation array; and finally, when the button element meets the same conditions as the link did earlier, it registers itself into the correct navigation array as a focusable element along with the parent it retrieves from the NavigationListProvider.

Return to Content Links

Summary

Consistent data registration and updating of each list's open state has been the priority of this release. There isn't anything visible on the screen, but a console.log(state.navigationArray) placed in the registerItemInNavigationArray function will show the completed array.

With the scaffolding complete, attention in the next release can turn to making those up and down arrow keys actually work. In the meantime, I'll be turning back to styling the navigation component for a vertical layout in the next article.

Laying it all Out

ShaynaProductions — Tue, 26 May 2026 12:15:00 +0000

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 article, functionality for keyboard handling on a single list was added, and I discussed how a lot of keyboard handling was to aid those who perceive through a screen and operate through the keyboard; a combination I realized has not been commonly considered by many of the developers I've worked with.

This article focuses once again on the screen's perceivability, with design considerations at the forefront.

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.4.1.

Examples have been updated in this release, enabling keyboard handling for a single list. Examples include a vertically aligned single list and horizontally aligned components with links and buttons for verifying operability.

The design requirements for this release are available.

Follow along either by downloading the release and running the examples while examining the codebase, or by activating the link accompanying each code snippet to view the full file on GitHub.

Content Links

Introduction
Layout
- Top Row Layout
- SubList Layout
  - Sharing Information
  - SubNavigation
Appearance
- Buttons and Links
- SubLists
Summary

Introduction

With an accessible HTML structure and the ability to transform objects into navigation, attention can finally be turned to styling. In this article, I'm focusing on the layout of the horizontal navigation, and then I'll apply some styling to buttons and links to achieve consistency and fit within the layout.

For all its promise, CSS has been notoriously difficult to create and maintain, relying on long chains of selectors to achieve specificity. These long selector chains hinder understanding and maintainability. Switching to nested CSS alongside structural HTML elements and implementing the @layer rule has been a boon, making it much simpler to create and maintain consistent layouts.

Any layout, whether component or page, needs to handle resizing without breaking proportions and styling, whether through browser zoom or when a user changes the base font size. Without a solid layout, any resizing required by WCAG success criteria 1.4.4 Resize Text is not achievable.

The image above, using the browser default font size of 16px, is unstyled except for the styling applied to the individual base components.

Even unstyled, resizing text doesn't break much, and a basic layout has been achieved thanks to the minimal CSS and theming applied to the base components. There's some shifting going on, but that will be handled as styles are applied.

Return to Content Links

Layout

Layouts are styled first, and while padding and positioning might need work later, even a rough layout helps.

Desktop navigation typically requires a top row laid out horizontally, with any sublists displayed vertically. So layouts for the top row and the sublist need to be styled separately.

Top Row Layout

@layer system-component {
    nav.horizontal-navigation {
        /* Layout */
        --min-list-width: var(--sp-px);
        padding: calc(var(--sp-px) * 16) 0;

        & > ul {
            align-items: normal;
            justify-items: flex-start;
            column-gap: calc(var(--sp-px) * 24);

            & > li {
                display: flex;
                align-content: center;
                align-items: center;
                position: relative;

                & > button,
                & > a[href] {
                    padding-left: 0;
                }
            }
        }
    }
}

GitHub (release 0.4.1) - styledHorizontal.css

A horizontal navigation can be considered a system component, so its styling is placed in the system-component layer. In a nested CSS structure, everything can be styled with a single class applied to the top-level element, in this case <nav />. Top and bottom padding are applied to the nav element to provide some space. A design token --min-list-width, to be discussed later, is set purely as a default.

Working on the top row first, rules are set for the nav element's only direct descendant, the topmost unordered list; The list element already sets display: flex and the basics for both horizontal and vertical displays, so the only necessary rules here are around alignment and setting a 24 relative-pixel column gap. Only list items that are directly descended from the element's top unordered list are given position: relative and have some flex alignment rules applied. The top-row buttons and links remove any left padding.

Now, a straight, horizontal line can be drawn at the element's base to verify that the top row links and the button text are aligned. Spacing is consistent across the top row, and with a 24 relative-pixel column gap, there is plenty of room between the focusable elements to meet WCAG success Criterion 2.5.8, Target Size (minimum).

Return to Content Links

SubList Layout

@layer system-component {
    nav.horizontal-navigation {
        /* Layout */
        /* Top Row nav > ul > li */

        & > ul {
            ... & > li {
                position: relative;

                ...
                    /* sub navigation (not top row) */

                & > ul {
                    min-width: calc(var(--sp-px) * var(--min-list-width));
                    padding: 0;
                    position: absolute;
                    top: calc(var(--sp-px) * 36);
                    width: fit-content;
                    z-index: 3;

                    & li {
                        width: 100%;

                        &:first-child {
                            padding-top: calc(var(--sp-px) * 8);
                        }

                        &:last-child {
                            padding-bottom: calc(var(--sp-px) * 8);
                        }
                        & button,
                        & a[href] {
                            display: flex;
                            flex-direction: row;
                            flex-wrap: nowrap;
                            justify-content: flex-start;
                            padding:
                                    calc(var(--sp-px) * 8)
                                    calc(var(--sp-px) * 16)
                                    0
                                    calc(var(--sp-px) * 8);
                        }
                    }

                    & ul {
                        padding: 0 calc(var(--sp-px) * 16) 0 0;
                        position: relative;

                        & > li {
                            padding-left: calc(var(--sp-px) * 16);
                        }
                    }
                }
            }
        }
    }
}

GitHub (release 0.4.1) - styledHorizontal.css

Sharing Information

Subnavigation lists can be styled as a direct unordered list descended from any list item in the top row. These lists are positioned as absolute, tied to their top-row list item, which is set to a relative position. Subsequent unordered lists are repositioned as relative, and the first and last list items within the subnavigation list receive extra vertical padding. Most of the padding is applied to the button and the link, along with flex styling.

The unordered list containing all subnavigation beneath a top-row button has a minimum width set via the design token --min-list-width. While a default was added, the question becomes, where is this token actually set?

I touched on this technique when discussing the Icon component in my article on base components, using the style attribute to communicate information between JavaScript and CSS. In this case, I want to guarantee the minimum width for a sublist is the same as the width of its button in the top row. So modifications need to be made to the SubNavigation component.

SubNavigation

export default function SubNavigation({...}) {
   ...

  const [isSubListOpen, setIsSubListOpen] = useState(false);
  const [listWidth, setListWidth] = useState(1);

  …
  useLayoutEffect(() => {
    setListWidth( buttonRef.current!.offsetWidth);
  }, [buttonRef, setListWidth]);

  ...

  const listItemProps = {
    cx: cx,
    style: { "--min-list-width": listWidth } as CSSProperties,
  };

  …
}

GitHub (release 0.4.1) - SubNavigation.tsx

A listWidth is set up in state, and a useLayoutEffect calls a function to set the list width, passing the buttonRef and dispatch to a custom utility function. The result is sent to the ListItem's style attribute through the design token, and the sub-list defined in SubNavigation uses the token to set a min-width.

You'll note the use of useLayoutEffect in the code. It is a synchronous function that runs only after React has performed all DOM mutations, but before the browser repaints, making it useful for DOM measurements. In this case, I'm using the button's offsetWidth property as the value for the design token I'm passing to the list item's style attribute.

I'm not a fan of pushing a lot of styles through the style attribute, but I do find it useful to send information only available to JavaScript to CSS.

export const setSubListWidth = (refObject, setListWidth) => {
  setListWidth(refObject.current?.offsetWidth);
};

GitHub (release 0.4.1) - utilities.ts

The read-only offsetWidth property is available on any HTML element. It returns a pixel measurement of an element's width, including borders and padding. Sublists can use the returned width, as defined by the top-row button, to set a relative pixel width, guaranteeing the list appears at least as wide as the button that controls it.

While nothing appears to be broken at any browser font size, it's hard to tell whether the layout is correct without applying other styles.

Return to Content Links

Appearance

@layer system-component {
    nav.horizontal-navigation {
        /* Layout */
        --min-list-width: var(--sp-px);
        padding: calc(var(--sp-px) * 16) 0;

        /* Top Row nav > ul > li */

        & > ul > ul {
            gap: unset;
        }

        & li {
            white-space: nowrap;

            & button,
            & a[href] {
                background-color: transparent;
                border-color: transparent;
                border-radius: 0;
                border-width: calc(var(--sp-px) * 1);
                color: var(--component-text-color);
                width: 100%;
                text-align: left;
            }
        }
    }
}

GitHub (release 0.4.1) - styledHorizontal.css

Buttons and Links

The component-level gap is unset for each ul directly descended from the top-level ul, and buttons and links have their appearance standardized. Background and border colors are set to transparent, allowing the elements to blend into the designated background color. A border-width is applied, along with a transparent border color, to prevent state changes from causing label shifting. Colors are applied through the theming system.

I want buttons and links to take up the entire list item, so the width is set to 100%. This increases the target size to that of the list item, which, while also visually appealing, conforms to WCAG success Criterion 2.5.8, Target Size (minimum).

Some changes to the underlying component styling are necessary. A gap originally set up in the styles associated with the list component is unset, and text alignment is reset to left instead of the original button style of center. Additionally, any item within a list item is set to keep text on a single line rather than wrap over multiple lines.

Return to Content Links

The styling is showing promise, but there's still more to do with the sublists.

SubLists

@layer system-component {
    nav.horizontal-navigation {
        /* Layout */

        ...& > ul {
            ...
        }
        ...
        & > ul {
            & > li {
                & button,
                & a[href] {
                    font-weight: 500;
                }

                & > ul {
                    background-color: var(--theme-background);
                    border-color: var(--component-border-color);
                    border-style: solid;
                    border-width: calc(var(--sp-px) * 1);

                    & button,
                    & a[href] {
                        font-weight: 400;
                    }

                    & ul {
                        border-color: transparent;
                    }

                    & > li {
                        font-weight: normal;
                    }
                }
            }
        }
    }
}

GitHub (release 0.4.1) - styledHorizontal.css

A background for links and buttons is finally applied, so text under the absolutely positioned sublists no longer bleeds through. Font weights are applied along with a border.

Is it perfect? There's always more to do, but both the top row and the displayed sublists are readable, and each focusable element in the sublists has a target area larger than the minimum target size.

It also looks consistently proportioned when the browser font size is increased.

Return to Content Links

Summary

The initial layout of a horizontal navigation component is simplified by nesting the CSS under a single class and using direct descendant selectors to target the top row and its sublists. Layout is separated from appearance, and the component remains consistent in proportions and ratios when a larger browser font is applied.

Single List Keyboard Handling

ShaynaProductions — Thu, 21 May 2026 12:15:00 +0000

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 article, the focus was actually on creating the components and adding a transformation utility to convert JavaScript objects into actual navigation. The base navigation component at this stage supports screen reader functionality through structured HTML and WAI-ARIA attributes, the ability to open and close a list through pointers and the Enter and Space keys.

This article, along with its accompanying release, focuses on basic keyboard handling for screen/keyboard users in a single list.

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.4.1.

You can view the requirements for the Single List Keyboard Release along with previous requirements.

Follow along either by downloading the release and running the examples while examining the codebase, or by activating the link accompanying each code snippet to view the full file on GitHub.

Content Links

Introduction
Acceptance Criteria
Holding Data in a Provider
- NavigationListProvider
- navigationListReducer
- useNavigation
Registering a Focusable Element
- NavigationList
- NavigationItem
- SubNavigation
Keyboard Handler
- useNavigationList
- NavigationItem
  - handleCommonKeyDown
- SubNavigation
Summary

Introduction

This article is the first of three detailing keyboard handling in a universally accessible navigation component; It is also the simplest.

In my experience, many developers seem to expect keyboard handling to be a browser feature, and it's been rare on the contracts I've worked on to see code that handles much custom keyboard input. Keyboard handling works well with native browser elements, but not as well with custom widgets, where developers need to handle code navigation requirements.

While most developers seem to understand that a keyboard is necessary for screen reader users, the fact that many people use a keyboard alongside a screen to navigate isn't always obvious. Users of screen readers have a variety of key combinations they may use to navigate through structures such as headings, links, form elements and tables. Users who navigate the screen with a pointer can simply move their cursor to a specific element and click. Unfortunately, the keyboard flexibility is limited for screen/keyboard users, who are the only ones who must navigate a page linearly. Navigation is not as easy for someone who can see a screen and depends on a keyboard for both input and navigation.

Those who use a screen and keyboard have expectations that developers should not only be aware of, but should strive to match. For those developers who work with a screen, testing how focus moves within a component is actually easy; just use the keyboard. Developers should always ensure a component is fully navigable with the Tab/Shift+Tab key combinations, which are required for both screen and screen reader users, and that any custom keyboard handling for screen users is implemented and works correctly.

To do so, developers need to receive acceptance criteria that detail what happens when a key is used.

When developers don't receive information about keyboard handling requirements when implementing a custom widget, efforts to bring the code into compliance with accessibility standards can run into snags. Keyboard handling can be compromised, and what actually gets implemented might be more focused on the letter of the law than the spirit, as is demonstrated by the following video.

Since the focus of this navigation component is accessibility, the acceptance criteria must specify what happens on each key press.

Return to Content Links

Acceptance Criteria

Single List Keyboard Handling

AC 1 - Pressing the HOME Key should take a user to the first item in the current List.
AC 2 - Pressing the END Key should take a user to the last item in the current list.
AC 3 - Pressing the LEFT-ARROW key should take a user to the previous item in the current list.
AC 4 - If focus is already on the first item in the current list, pressing the LEFT-ARROW key should take the user to the last item in the current list.
AC 5 - Pressing the RIGHT-ARROW Key should take a user to the next item in the current list.
AC 6 - If focus is already on the last item in the current list, pressing the RIGHT-ARROW Key should take a user to the first item in the current list.

The keyboard support section in the Disclosure Navigation pattern in the APG requires interpretation. The guide references moving buttons to buttons and links to links. Both are focusable elements, and depending on where each lies, navigation can move from a button to a link, or from a link to a button, within a single list.

Hand-eye coordination is key in this instance. We expect the cursor to move in the direction indicated by the arrow keys. When the cursor moves to an unexpected location, it's jarring; if it disappears entirely, the site can appear broken.

Return to Content Links

Holding Data in a Provider

Navigation in a sublist requires a focusable element, in this case either a button or a link, to be able to determine its sibling in a list and move according to the acceptance criteria.

Each link and button in a list is rendered in its own component, with no real way to know about, much less access, the others.

Data for each focusable item in a particular list can be stored in a context provider, along with functions to register and retrieve the collective data. Since each focusable element is part of a list, the best data structure to hold the information is an array.

NavigationListProvider

Context providers hold data along with functions for retrieving and setting it. Each list works with its own copy of the provider, and the data in its array consists of each individual link or button element within the list items it contains. Each focusable element, whether a button or a link, can only focus on siblings contained in the list it resides in.

export function NavigationListProvider({ children }) {
  const [state, dispatch] = useReducer(navigationListReducer, {
    items: [],
  });

  const getCurrentListItems = useCallback(() => {
      return state.items;
    }, [state.items]);

  const registerItemInCurrentList =  useCallback((focusableEl) => {
      dispatch({ type: "REGISTER_ITEM", item: focusableEl });
    }, []);

  return (
    <NavigationListContext.Provider
      value={{
        getCurrentListItems,
        registerItemInCurrentList,
      }}
    >
      {children}
    </NavigationListContext.Provider>
  );
}
NavigationListProvider.context = NavigationListContext;

GitHub (release 0.4.1) - NavigationListProvider.tsx

Given the nature of the data, useReducer is a better solution than useState. A reducer still uses the state object but can manage more complex logic. Since state updates to the NavigationListProvider affect multiple components and changes might depend on others, it makes sense to use the provided reducer hook rather than the state hook.

navigationListReducer

export function navigationListReducer(
  state,
  action,
) {
  switch (action.type) {
    case "REGISTER_ITEM": {
      if (state.items.includes(action.item)) return state;
      return { ...state, items: [...state.items, action.item] };
    }
    default: {
      return state;
    }
  }
}

GitHub (release 0.4.1) - navigationListReducer.ts

Like most reducers, actions are held in a switch, even though there is only one action type, REGISTER_ITEM. When called, a focusable element (action.item) is passed through and checked to determine if it already exists in the array. If not, it is added in.

A context provider is not exposed to public components; instead, a hook is used to execute functionality that can be passed through the registration function and to add additional functionality when necessary.

useNavigationList

export function useNavigationList() {
  const navigationListContextObj = use(NavigationListContext);
  const { registerItemInCurrentList } =
    returnTrueElementOrUndefined(
      !!navigationListContextObj,
      navigationListContextObj,
    );

  return {
    registerItemInCurrentList,
  };
}

A common pattern for a hook associated with a context provider is to load the provider's public functions and either use them in the hook or pass them through to another component. For the moment, the registration function is just passed through, so it may be imported into the navigation components.

Return to Content Links

Registering a Focusable Element

In order for the array to be used with keyboard handling, the focusable elements must be registered (added) into the data array. The first step is to wrap each list within its own context provider.

NavigationList

export default function NavigationList({...) {
  const listProps= {...};

  return (
    <NavigationListProvider>
      <List key={`list-$id`} {...listProps}>
        {children}
      </List>
    </NavigationListProvider>
  );
}

GitHub (release 0.4.1) - NavigationList.tsx

With the NavigationListProvider now wrapping the List component, each list item can access any other list item stored in its copy of the data array. It's important to understand that each list maintains its own array of items and cannot access items across lists.

NavigationItem

export default function NavigationItem({...}) {
  const {
    registerItemInCurrentList,
  } = useNavigationList();

  const currentPath = ...;

  const linkRef = useRef(null);

  useEffect(() => {
    if (linkRef.current !== null) {
      registerItemInCurrentList(linkRef.current);
    }
  }, [ linkRef, registerItemInCurrentList]);


  const listItemProps = { ... };

  const linkProps = {
    ... ,
    ref: linkRef,
    ...rest,
  };

  return ( ... );
}

GitHub (release 0.4.1) - NavigationItem.tsx

Code that has already been discussed in previous releases is represented by ellipses; only new code is given.

Focusable elements are stored in ref objects, but reading the element through ref.current can lead to unreliable code during renders. Since the elements held in the ref object are just pointers to the DOM elements, it's safe to extract them and store them separately as read-only.

References to elements are not populated right away; the focusable element, in this case a link, needs to be rendered before the information is available, so the useEffect() that registers the link into the currentlistitems array only runs when the ref. current is not null.

SubNavigation

export default function SubNavigation({...}) {
  const {
    registerItemInCurrentList,
  } = useNavigationList();

  const buttonRef = useRef(null);

  const [isSubListOpen, setIsSubListOpen] = useState(false);

  useEffect(() => {
    if (buttonRef.current !== null) {
        registerItemInCurrentList(buttonRef.current);
    }
  }, [buttonRef, registerItemInCurrentList]);

  const handlePress = () => {
    setIsSubListOpen(!isSubListOpen);
  };
    ...
    ref: buttonRef,
  };
  ...
}

GitHub (release 0.4.1) - SubNavigation.tsx

The code to register a button is almost identical to the code registering a link. The only difference is that the reference being passed is a button element.

Return to Content Links

Keyboard Handler

With the data structure set up and items registered, it's finally time to shift the focus to handling the appropriate keys, and attention turns back to the acceptance criteria.

AC 1 - Pressing the HOME Key should take a user to the first item in the current List.
AC 2 - Pressing the END Key should take a user to the last item in the current list.
AC 3 - Pressing the LEFT-ARROW key should take a user to the previous item in the current list.
AC 4 - If focus is already on the first item in the current list, pressing the LEFT-ARROW key should take the user to the last item in the current list.
AC 5 - Pressing the RIGHT-ARROW Key should take a user to the next item in the current list.
AC 6 - If focus is already on the last item in the current list, pressing the RIGHT-ARROW Key should take a user to the first item in the current list.

The only keys being handled now are home, end, and the left and right arrows. If the focus is on the first element in the list and the left arrow key is pressed, then focus should jump to the last element in the list, and the opposite should happen if the focus is on the last element and the right key is pressed. Focus should move to the first element.

useNavigationList

Since the functionality needs to access data stored in the context provider, the functions are created in the hook.

 export function useNavigationList() {
  const navigationListContextObj = use(NavigationListContext);
  const { getCurrentListItems, registerItemInCurrentList } =
    returnTrueElementOrUndefined(
      !!navigationListContextObj,
      navigationListContextObj,
    );

  const currentListItems = getCurrentListItems();

  const _getCurrentIndex = useCallback(
      (currentlyFocusedEl) => {
        return currentListItems.indexOf(currentlyFocusedEl);
      },
      [currentListItems],
    );

    const shiftFocus= ( focusableEl) => {
      focusableEl.focus({ preventScroll: true });
    };

    const setFirstFocus = () => {
      shiftFocus(currentListItems[0]);
    };

    const setLastFocus = () => {
      shiftFocus(currentListItems[currentListItems.length - 1]);
    };

    const setNextFocus = ( currentlyFocusedEl) => {
      const newIndex = _getCurrentIndex(currentlyFocusedEl) + 1;
      if (newIndex >= currentListItems.length) {
        setFirstFocus();
      } else {
        shiftFocus(currentListItems[newIndex]);
      }
    };

    const setPreviousFocus = ( currentlyFocusedEl) => {
      const newIndex = _getCurrentIndex(currentlyFocusedEl) - 1;
      if (newIndex < 0) {
        setLastFocus();
      } else {
        shiftFocus(currentListItems[newIndex]);
      }
    };

    return {
      registerItemInCurrentList,
      setFirstFocus,
      setLastFocus,
      setNextFocus,
      setPreviousFocus,
      shiftFocus,
    };
}

GitHub (release 0.4.1) - useNavigationList.tsx

A reminder that the code discussed earlier is represented by ellipses; only the new code is shown.

It's useful to know when a private or public function is used, and I do so by prefacing private functions with an underscore.

To provide a fresh copy of the data to the hook, don't call the data directly; it won't refresh. Instead, a getter is retrieved from the context provider, getCurrentListItems(). You'll note an alias for currentListItems that calls the getter each time. When used this way, the code always returns an updated copy of the array, making it more natural to work with.

A custom function, shiftFocus(), is used instead of implementing focus within each publicly called function to standardize how scrolling is handled. In these cases, scrolling should be prevented when navigation is displayed in a horizontal layout to prevent extraneous shifts when sublists open and close.

The rest of the code is self-explanatory; focus is shifted depending on the key pressed: Home and End, sends focus to the first or last children in the list, while the right or left arrow key sets focus depending on where the currently focused element is; If the focus is at the end of the list when setNextFocus is called, focus then moves to the first element and if the focus is at the beginning of the list when setPreviousFocus is called, focus moves to the end. Otherwise, focus shifts to the respective sibling on either side of the current element.

With the focus functions created, it's time to use them.

NavigationItem

export default function NavigationItem({ ... }) {
  const {
    registerItemInCurrentList,
    setFirstFocus,
    setLastFocus,
    setNextFocus,
    setPreviousFocus,
  } = useNavigationList();
  const currentPath = ...;
  …

 const handleKeyDown = (e) => {
      const linkEl = linkRef.current;

      switch (e.key) {
        case Keys.HOME:
        case Keys.END:
        case Keys.LEFT:
        case Keys.RIGHT:
          e.preventDefault();
          e.stopPropagation();
          break;
      }

      handleCommonKeyDown(
        e,
        linkEl,
        setFirstFocus,
        setLastFocus,
        setNextFocus,
        setPreviousFocus,
      );
    };
  …

  const linkProps = {
    ...
    onKeyDown: handleKeyDown,
    ref: linkRef,
    ...rest,
  };

  return (..);
}

The setters from the hook are retrieved, and a handleKeyboard function is created. Rather than setting preventDefault and stopPropagation in each case statement, I use a switch that sets them on all the keys at once. And because both links and buttons handle these keys in the same way, a common keyboard handler is created and called rather than duplicating the code across components.

When calling a function outside the render, everything necessary must be passed in, including all the hook calls.

handleCommonKeyDown

export const handleCommonKeyDown = (
  e,
  currentlyFocusedEl,
  setFirstFocus,
  setLastFocus,
  setNextFocus,
  setPreviousFocus
) => {
  switch (e.key) {
    case Keys.HOME:
      setFirstFocus();
      break;
    case Keys.END:
      setLastFocus();
      break;
    case Keys.LEFT:
      setPreviousFocus(currentlyFocusedEl);
      break;
    case Keys.RIGHT:
      setNextFocus(currentlyFocusedEl);
      break;
  }
};

GitHub (release 0.4.1) - handleCommonKeyDown.tsx

The common key handler is quite straightforward; each specific key triggers a function in the hook to decide the next item to shift to.

SubNavigation

export function SubNavigation({...}) {
    const {
        currentListItems,
        parentRef,
        registerListItem,
        setFirstFocus,
        setLastFocus,
        setNextFocus,
        setPreviousFocus
    } = useNavigationList();
   const {
        registerListItem, 
        setFirstFocus, 
        setLastFocus, 
        setNextFocus, 
        setPreviousFocus} = useNavigationList();

   const buttonRef = useRef(null);
    ...

  useEffect(() => {
    const currentButtonEl = buttonRef.current;
    if (currentButtonEl !== null) {
       registerItemInCurrentList(currentButtonEl);
    }
  } , [buttonEl, buttonRef, isSubListOpen, registerItemInCurrentList]);

    const handleKeyDown = (e) => {
        const buttonEl = buttonRef.current;

        switch (e.key) {
            case Keys.HOME:
            case Keys.END:
            case Keys.LEFT:
            case Keys.RIGHT:
                e.preventDefault();
                break;
        }

        handleCommonKeyDown(
          e, 
          buttonEl, 
          setFirstFocus, 
          setLastFocus, 
          setNextFocus, 
          setPreviousFocus
       );

    ...

    const buttonProps: ButtonProps = {
        ...
        onKeyDown: handleKeyDown,
        onPress: handlePress,
        ref: buttonRef,
        ...
    };

    ...
    return ( ...)
}

GitHub (release 0.4.1) - SubNavigation.tsx

Notice how stopPropagation() is not included in the top switch. This is because the button component I use from react-aria-components already calls stopPropagation() itself, so I don't need to set it. This may differ from the button component you are working with. Otherwise, the code for SubNavigation is similar to that already seen in NavigationItem.

Return to Content Links

Summary

Handling link references to multiple components becomes straightforward when a provider holds the data and the functions that call and manipulate it. A hook passes through the necessary provider functions, as well as its own, to provide keyboard handling within a single list.

With all the code added to support single-list keyboard handling, the question arises: Does it work?

Part of the issue with demonstrating keyboard handling is the inability to show which key is being used as focus moves. It's one of the reasons keyboard accessibility is so hard to demonstrate during sprint demos. I'll be providing videos I make that detail what I am doing and which keys I'm pressing as I guide you through the enhancements.

I'll be back with another article soon, focusing on CSS design and applying a layout to the default horizontal navigation.