DEV Community: ShaynaProductions

Styling the Vertical - Achieving Parity

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

Note: This article is one of a series demonstrating building a React navigational component from scratch while considering accessibility through the process. The articles are accompanied by a GitHub repository with releases tied to one or more articles; each builds on the previous one until a fully implemented navigation component is complete.

Each release and its associated tag contain fully runnable code for the article. The code discussed in this article is available in the release. and may be downloaded at release 0.9.0. A page showcasing these base components may be run locally through this release.

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

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.

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.

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.

Structure and Transformation: First Steps in Navigation Implementation

ShaynaProductions — Tue, 19 May 2026 13:25:33 +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 the last article, the focus was on wiring a theme into the foundational components that render valid HTML elements. This article focuses on creating the navigation structure and on transforming objects into a navigation component suitable for further work by developers for operability and by designers for perceivability.

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

You can view the requirements for the Structure and Transformation 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.

-—

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 return to the discussions of the individual components.

Content Links

Introduction
Acceptance Criteria
Structure
- NavigationList
- NavigationItem
- SubNavigation
- Navigation
- navigation.css
Transformation
Summary

Introduction

Non-trivial component development requires progressively enhancing code through a layered approach. Each release builds on the previous release, adding accessibility, functionality, and even some styling to the earlier work. Consider building these components on a feature branch and merging into main only after they are complete.

With the base components completed, attention turns to the components necessary to render the nested structure of unordered lists contained in the landmark element. Screen reader accessibility and minimal target functionality via button activation are also added, resulting in a fully rendered navigation component that can be displayed in examples and used in testing.

All examples display the default choice for an uncontrolled component with full aria capabilities, along with some slight styling to provide developers with visual indications of placement. When run locally, the home page exposes three ugly, yet operable examples for development and testing. Taken together, the three examples cover all of the scenarios necessary to create a robust, uncontrolled navigation component.

Acceptance Criteria

Structure and Transformation Release

AC 1 - The Navigation Component should be contained in a landmark region
AC 2 - The navigation should be presented as a nested structure of unordered lists within the landmark region
AC 3 - Lists should present with a role of "list", list Items should present with a role of "listitem".
AC 4 - Buttons are associated with a sublist and indicate if the sublist is open or closed.
AC 5 - The navigation component should be able to be presented as horizontal (desktop - default).
AC 6 - When navigation is displayed in a horizontal layout, the first row of focusable elements should display as open by default.
AC 7 - The navigation component should be able to be presented as vertical (mobile presentation).
AC 8 - A visual indicator is used to represent the state of the sublist's expanded status.
AC 9 - A link should contain a method of informing users which link corresponds to the current page for both screen and screen readers.
AC 10 - A sublist may be toggled to open or close when the button associated with it is pressed.
AC 11 - The state of a list's visible or hidden state should be easily perceived by any user
AC 12 - Unexpanded sublists should be hidden from the screen, but available through the DOM when they are closed.
AC 13 -A JavaScript object containing a properly formed object should be able to be transformed into properly formed ListItems and Subnavigation lists.

While most of the requirements were known during the initial requirements gathering phase, two more have been added.

AC 12 represents the decision to render unopen lists in the DOM while restricting their visibility on a screen. This decision and the reasons for it were made in the initial requirements gathering phase.

AC 13 requires a utility function that can take a JavaScript object and output a fully formed set of navigation lists and links to form the nested structure necessary.

Return to Content Links

Structure

Given the requirements, the following components are necessary and will be built in the following order:

NavigationList: A wrapper around the List component that allows for children and designates whether the list itself is displayed on the screen.
NavigationItem: Renders a Navigation Link within a ListItem and reveals the link referring to the current page. (aria-current).
SubNavigation: Renders both a button and its accompanying sublist within a listItem. Handles displaying or hiding the sublist on the screen when the button is pressed.
Navigation: Renders the entire navigation lists and sublists within a HTML element.

NavigationList

Acceptance Criteria Realized

AC 3 - Lists should present with a role of "list", list Items should present with a role of "listitem".
AC 5 - The navigation component should be able to be presented horizontally (desktop presentation).
AC 7 - The navigation component should be able to be presented as vertical (mobile presentation).
AC 12 - Unexpanded sublists should be hidden from the screen, but available through the DOM when they are closed.

export default function NavigationList({
  children,
  cx,
  id,
  isOpen,
  ...rest
}) {
  const listProps = {
    ...rest,
    id,
    cx: classNames({ srOnly: !isOpen }, cx),
  };

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

GitHub (release 0.3.1) - NavigationList.tsx

A NavigationList wraps around the previously created List component, which renders the structural HTML (AC 3). An unordered list (ul) has a default role of "list".

While not detailed in the code, an orientation prop is passed to the List component via …rest, that indicates whether the list is displayed horizontally or vertically (AC 5 and 7). This was placed into the List component during the base component functionality phase.

The isOpen prop controls the screen visibility of the specific list by applying the .srOnly class when the list is unexpanded and removing it when isOpen is true, satisfying AC 12. A screen reader-only class hides the content from the screen while still making it available to screen readers.

Because the transform utility iterates over an array, a key is passed to the List component.

Return to Content Links

NavigationItem

Acceptance Criteria Realized

AC 3 - Lists should present with a role of "list", list Items should present with a role of "listitem".
AC 9 - A link should contain a method of informing users which link corresponds to the current page for both screen and screen readers.

export default function NavigationItem({
  cx,
  href,
  id,
  label,
  ...rest
}) {
  const currentPath = usePathname();

  const pageURL = href.substring(0, 2) === "/#" ? currentPath + href : href;

  const listItemProps: Omit<ListItemProps, "children"> = {
    cx: cx,
    id: id,
  };
  const linkProps: Omit<LinkProps, "children"> = {
    "aria-current": returnTrueElementOrUndefined(currentPath === href, "page"),
    "aria-label": `${label} navigation`,
    href: pageURL,
    ...rest,
  };

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

GitHub (release 0.3.1) - NavigationItem.tsx

While not a detailed requirement, and mostly useful for tests and examples, the system does check for anchors passed through, and if an anchor is the only href aspect passed through, the path of the currently loaded page is prepended to the URL, which is ultimately passed to the link. Care should be taken that any objects used in production do not allow the passage of "/#".

When a link is identical to the page currently loaded, the aria-current prop should be set to "page" (AC 9) but otherwise should be undefined. I'm using the NextJS function usePathname() to achieve this; your solution may be different.

Even though nothing in the acceptance criteria requires it, an experienced developer will add information to the link about its purpose. Adding "navigation" to the label helps satisfy WCAG 2.4.9 Link Purpose by guaranteeing anyone using a screen reader understands that the links in the elements list/rotor are navigation-related. The label is prepended to the "navigation" description, satisfying WCAG 2.5.3 Label in Name for those who use their voice to interact with the component.

Once again, a key is added to the ListItem component call since a ListItem can be rendered through an array map iteration.

Return to Content Links

SubNavigation

Acceptance Criteria Realized

AC 4 - Buttons are associated with a sublist and indicate if the sublist is open or closed.
AC 8 - A visual indicator is used to represent the state of the sublist's expanded status.
AC 10 - A sublist may be toggled to open or close when the button associated with it is pressed.
AC 11 - The state of a list's visible or hidden state should be easily perceived by any user

export default function SubNavigation({
  children,
  cx,
  id,
  label,
  testId,
}) {
  const [isSubListOpen, setIsSubListOpen] = useState<boolean>(false);

  const handlePress = () => {
    setIsSubListOpen(!isSubListOpen);
  };

  const buttonProps = {
    "aria-controls": id,
    "aria-expanded": isSubListOpen,
    "aria-label": `${label} subnavigation`,
    onPress: handlePress,
  };

  const iconProps = {
    IconComponent: ChevronRightIcon,
    isSilent: true,
  };

  const listItemProps = {
    cx: cx,
  };

  const navigationListProps = {
    id: id,
    isOpen: isSubListOpen,
    testId: testId && `${testId}-list`,
  };
  return (
    <ListItem key={id} {...listItemProps}>
      <Button {...buttonProps}>
        {label}
        <Icon {...iconProps} />
      </Button>
      <NavigationList key={`list-${id}`} {...navigationListProps}>
        {children}
      </NavigationList>
    </ListItem>
  );
}

GitHub (release 0.3.1) - SubNavigation.tsx

The entire subnavigation component is wrapped in a ListItem, which contains a Button and a NavigationList. This is the basis for creating a properly nested list within the navigation component. As with the NavigationItem component, the ListItem must include a key to meet React's requirements when generating the navigation from a JavaScript object.

A button that controls another element, in this case the NavigationList component, associates itself with the NavigationList via the aria-controls attribute, which links to the NavigationList's id. Buttons also use the aria-expanded attribute to denote whether the item it controls is visible (aria-expanded ="true") or hidden (aria-expanded="false"). It's one of the few aria attributes where both true and false give meaning, and so it is always a boolean value. Additionally, an icon is included as a child of Button, indicating to screen-viewing users that the item is not a link and, when toggled, rotating between 0 and 90 degrees to indicate the list's visibility, satisfying AC 8. The actual visibility of the list can also be said to achieve AC 8.

Along with their link counterparts, buttons are available in a different collection of a screen reader's list elements/rotor, and appending "subnavigation" satisfies the same WCAG success criterion.

Return to Content Links

Navigation

Acceptance Criteria Realized

AC 1 - The Navigation Component should be contained in a landmark region.
AC 2 - The navigation should be presented as a nested structure of unordered lists within the landmark region.
AC 6 - When navigation is displayed in a horizontal layout, the first row of focusable elements should display as open by default.

export default function Navigation({
  children,
  cx,
  isOpen = true,
  label,
  orientation = "horizontal",
  ...rest
}) {
  const navigationProps = {
    "aria-label": label,
    className: cx,
  };

  const navigationListProps = {
    ...rest,
    isOpen,
    orientation,
  };

  return (
    <>
      <nav {...navigationProps}>
        <NavigationList {...navigationListProps}>{children}</NavigationList>
      </nav>
    </>
  );
}

GitHub (release 0.3.1) - Navigation.tsx

The navigation component wraps the first call to the NavigationList component within the landmark, indicating that the component represents navigation and includes a label that identifies it to a screen reader. (AC 1). An uncontrolled component will always return the initial state of the top row as open and set an orientation of horizontal on the first row (AC 6), which is passed through to the NavigationList.

Minimal styling is applied to the navigation component to rotate the icon when a button is toggled.

navigation.css

@layer common-components {
    nav {
        & svg {
            left: calc(var(--sp-px) * 8);
            position: relative;
        }

        & button[aria-expanded="true"] svg {
            rotate: 90deg;
        }
    }
}

GitHub (release 0.3.1) - navigation.css

Most styling of a navigation component will take place elsewhere, but spacing and rotation of the icon are best handled within the component itself. As I mentioned before, I find it useful to style based on aria attributes rather than adding a class, letting my CSS add a small accessibility enforcement.

Return to Content Links

Transformation

When a developer manually creates navigation code can look similar to:

<Navigation>
    <NavigationItem id="item-one" href="/one" label="Item One" />
    <NavigationItem id="item-two" href="/two" label="Item Two" />
    <SubNavigation id="Sub-One" label="Sub Nav One" >
        <NavigationItem id="item-three" href="/tree" label="Item Three" />
    </SubNavigation>
</Navigation>

Of course, creating all the variants for examples and testing can be tedious, and realistically, the component's information will be read from a JavaScript object, whether from a static JSON file or an API via GraphQL. I also like standardizing examples across testing and browsers to make it easier to identify and fix issues.

[{
    "label": "Tales",
    "id": "tales-menu",
    "href": "",
    "menu": [
        {
            "label": "Search",
            "id": "search-menu",
            "href": "#",
            "menu": [
                {
                    "label": "Basic Search",
                    "id": "basic-search",
                    "href": "/#basicsearch"
                },
                {
                    "label": "Advanced Search",
                    "id": "advanced-search",
                    "href": "/#advsearch"
                }
            ]
        },
        {
            "label": "All Stories",
            "id": "all-stories",
            "href": "/#all-stories"
        },
        {
            "label": "All Commentary",
            "id": "all-commentary",
            "href": "/#all-commentary"
        },
        {
            "label": "Find Your Next Story",
            "id": "find-next-story",
            "href": "",
            "menu": [
                {
                    "label": "By Storyteller",
                    "id": "by-storyteller",
                    "href": "/#by-storyteller"
                },
                {
                    "label": "By Era",
                    "id": "by-era",
                    "href": "/#by-era"
                }
            ]
        }
    ]
},]

JSON Navigation Example GitHub (release 0.3.1) - multiple-lists-buttons.json

A subset of the multiple-lists-buttons.json file is detailed above. Upon examination, any link will have a valid href, and any button will contain a menu array. While the href attribute on a button isn't used, it must still be present to conform to the object type. Theoretically, subnavigation objects may be nested indefinitely, but for testing purposes, only two levels are featured.

The transform utility will take a full object and return the appropriately nested components to be rendered within the Navigation component.

Acceptance Criteria Realized

AC 13 - A JavaScript object containing a properly formed object should be able to be transformed into properly formed ListItems and Subnavigation lists.

export function transformNavigation(
    navigationArray,
    testId,
) {
    return navigationArray.map((item) => (
        <Fragment key={`navigation-${item.id}`}>
            {item.menu ? (
                <SubNavigation
                    key={item.id}
                    id={item.id}
                    label={item.label}
                    testId={testId && `${testId}-${item.id}`}
                >
                    {transformNavigation(item.menu, testId)}
                </SubNavigation>
            ) : (
                <NavigationItem
                    id={item.id}
                    key={item.id}
                    label={item.label}
                    href={item.href}
                    testId={testId && `${testId}-${item.id}`}
                />
            )}
        </Fragment>
    ));
}

GitHub (release 0.3.1) - transformNavigation

The transform utility is recursive, calling itself for objects contained in a menu array. Other than recursion, it's fairly straightforward. Loop through the object; if it contains a menu, render the Subnavigation component, then call itself to render the children defined in the menu object. If the item mapped does not have a menu, render a NavigationItem component.

When run in examples, the transformation returns a full navigation menu. And while it's obvious that a lot of work still needs to be done, there's now a solid foundation to work with.

Return to Content Links

Summary

With the transform utility, examples are now available in the release with just enough CSS to make operability feasible. Work can begin on horizontal and vertical menu styling.

At this moment, the navigation component meets screen reader perceivability requirements. It can be used via the keyboard with the Tab Key and the Enter or Space keys to toggle the sublist availability. All links and buttons are available in the screen reader elements list and correctly denote their purpose. Not bad for just a skeleton; in fact, I know several teams that would consider the navigation component complete at this point. I'm not one of them, though.

Next up will be the first of three releases dedicated solely to keyboard handling, concentrating on keyboard navigation through a single list.

Theming in the Modern Age

ShaynaProductions — Thu, 14 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 the last article, the focus was on the operability of foundational components that render valid HTML elements. This article focuses on screen perceivability and the foundational aspects around theming, design and CSS.

CSS is used to illustrate design concepts. To that end, the theming system I'm using is solely composed of stylesheets.

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

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.

Introduction

In modern web development, theming systems are everywhere. Many of them integrate directly with JavaScript frameworks and support component styling by converting JavaScript objects into CSS with preprocessors like Styled Components or CSS-in-JS. Not surprisingly, I have thoughts around this.

A tightly integrated theming system tied directly to JavaScript, such as Material-UI or Radix-UI, along with the requirement to write CSS within component files, can cause issues when upgrading or even moving to a different framework.

This tight integration breaks the principle of separation of concerns. A theming system should sit alongside the project it affects and be available no matter the framework or language used. To my mind, a theming system should work just as well in a static HTML site as it does within a front-end framework such as Angular or React and work seamlessly when something in the stack needs to change.

Modern CSS has evolved in leaps and bounds over the last few years. Psuedo-selectors such as :has() and :not() make targeting parent elements based on their children's attributes, or lack thereof, a reality. It's worth revisiting if you haven't looked at it in a while.

I've had a love/hate relationship with CSS for a long time. I love the cascade aspect of CSS, but most styling frameworks seem to give it up in favor of writing styles directly in JSX or TSX files, with everything applied as classes. This approach adds complexity and reduces maintainability, especially when tracing style issues across components. I find it harder to maintain consistent styling when CSS can't be applied consistently across components. Is it doable? Yes. Is it easy and intuitive? No.

For most of my career, CSS has seemed like something I fight rather than something that just works. Dealing with browser inconsistencies and the battle between the styles set by third-party component libraries, the desires of the various design teams I've worked with, alongside the requirement to keep all styling in components and style everything in a class, has been my reality for years. Working with designs created by those who've rarely considered specificity or cross-browser styles has been challenging. Not to mention the issues of overriding a component library's styles to conform to another's vision.

My vision for a theming system is one built on modern CSS, which, for the most part, sits alongside my React components. I've built it on four pillars.

Primitive components: are those components where the focus by the developers has been on operability and functionality, not on perceivability. These components are released without any CSS styles and are styled only by the browser in which it is run.
Sanitization scripts: to standardize styles across browsers and, in many cases, removing most of the visual styling, goes a long way toward reducing the headache of trying to make something look the same way across browsers.
CSS Cascade Layers: widely supported across browsers, allows for defining explicit contained layers of specificity, reducing the need for long strings of classes and the use of !important.
CSS Nesting: allows for writing more modular, maintainable and readable CSS. It's similar to SASS nesting, using the same & operator, but it also supports all the newer pseudo-element selectors, which sadly SASS hasn't kept up with.

Primitive Components

Open source primitive component libraries abound. Radix, React Aria Components, Reach, Reakit and AriaKit all provide unstyled components that emphasize operability and accessibility. There's no fighting over opinionated CSS because there is no opinion on how to style these components other than those of the people responsible for the design.

My current implementation uses react-aria-components, an underlying primitives library provided by Adobe.

Primitive libraries, which feature operable components with no styling applied, have reduced the need to reconcile component-agnostic styling with corporate directives. I will admit I was intimidated by the idea of adding all the styling necessary to components, but the payoff has been worth it.

Santitization Scripts

A good set of sanitization scripts goes a long way towards sane styling. Sanitization scripts remove the inconsistencies across browsers, and the one I use removes most visual styling altogether.

Developing a vanilla theming system using modern CSS, along with robust sanitization scripts and primitive components that are initially operable but not perceivable, has changed the way I think about the HTML elements I work with every day. The first time I loaded a sanitized, unstyled, empty button onto a page, I thought I did something wrong. My screen was blank; the only way I knew a button was loaded was by checking the DOM. I added a border width and style, still nothing. It was only when I applied a color to the border that a small box appeared. I added text to my button, and to my amazement, it was flexible: it had no specified height or width, and no padding or margins; it hugged its content tightly.

Standardizing on box-size: border-box made a huge difference. Suddenly, setting a specific width meant the element's width never changed. Border widths and padding sizes are part of the set width. True consistency is achievable.

CSS Cascade Layers

CSS Layers applies an order of precedence based on an @rule, reducing the need for specificity. Styles lower in the layer hierarchy are easily overridden by styles in higher layers, reducing the need for !important declarations and long, hard-to-follow selectors.

@layer reset, system, default-theme, base-component, common-component, system-component, main;

GitHub (release 0.2.1) - Theming System - layers.css

Layers within a theming system are self-defined. We determine which layers exist and which layers are higher in precedence. Layers are applied from left to right; any overrides in a layer defined to the right are applied without additional specificity or the need for !important.

In my layer system, I begin with reset, which contains my sanitization scripts that remove all padding and borders and standardize elements across browsers.

Anything defined in the reset layer may be overridden by the other layers, including the system layer, which holds design tokens for colors and underlying choices, such as the creation of my relative pixel base size and global srOnly class.

@layer system {
  :root {
    --sizing-base: 1rem;
    --sp-px: calc(var(--sizing-base) * 0.0625);
    --shadow-opacity: 0.3;
    --overlay-opacity: 0.2;
  }
  .srOnly {
    border: 0;
    clip: rect(1px, 1px, 1px, 1px); /* 1 */
    clip-path: inset(50%); /* 2 */
    height: 1px;
    margin: -1px;
    overflow: hidden !important;
    padding: 0;
    position: absolute !important;
    width: 1px;
    white-space: nowrap !important; /* 3 */
  }
}

GitHub (release 0.2.1) - Theming System - base.css

While layers reduce the need for the keyword, !important, it still has its uses. In the case of my srOnly class, the properties overflow, position and whitespace may not be overwritten no matter what. Since those three properties define removing the class applied element from the screen, they are integral to the style.

Layers address many of the issues around specificity and are well worth the time to get to know them. They form an integral part of my theming system.

CSS Nesting

Nested CSS, a fully supported feature of CSS, mimics SASS in some ways, and when implemented inside @layer, removes the need for chaining selectors and allows for more modularity. When base components render into actual structured HTML elements, the need for adding a class to everything disappears.

I think the mindset around CSS usage has suffered from the overuse of classes, and I blame Macromedia for their decision when creating Dreamweaver to make everything a class, which in turn has influenced a generation of developers. Trying to debug conflicting styles when everything is styled via a string of classes to provide enough specificity has turned many stylesheets into a morass where developers fear to tread.

When nested CSS is used alongside HTML elements rather than classes, everything starts to make sense.

@layer main {
  #base-components {
    & > ul.general {
      align-items: flex-start;
      column-gap: calc(var(--sp-px) * 16);
      display: flex;
      flex-direction: row;
      list-style: inside;
      width: 100%;

      & li {
        border-width: var(--component-border-width);
        border-style: solid;
        border-color: transparent transparent transparent var(--purple-3);
        list-style: none;
        padding-left: calc(var(--sp-px) * 16);
        padding-bottom: calc(var(--sp-px) * 16);
        width: 30%;
        &:first-child {
          border-left-color: transparent;
        }

        & a {
          text-decoration: underline;
        }
      }
    }

    & > ul:not(.general) {
      display: flex;
      gap: calc(var(--sp-px) * 16);
      position: relative;
      flex-wrap: wrap;
      list-style: none;

      & > li {
        padding: 0 calc(var(--sp-px) * 16);
        width: 47%;
      }

      & > li div {
        border-width: calc(var(--sp-px) * 8);
        padding: calc(var(--sp-px) * 32);
        mask: radial-gradient(
            calc(var(--sp-px) * 21) at 50% calc(var(--sp-px) * 21),
            #0000 calc(100% - var(--sp-px) * 1),
            #000) 50% calc(-1 * var(--sp-px) * 21) / calc(var(--sp-px) * 38.85) 100%;
      }
    }
  }
}

GitHub (release 0.2.1) - baseComponentsPage.css

The example above is a snippet styling the base components example page in the demo. Notice how everything cascades from a single id, using descendant selectors to drill down into elements and apply styling. All widths and gaps are either percentages or derived as relative pixels using the technique I described in a previous article, Spacing Considerations In Acessible Design.

With these four pillars in place, everything I dreaded about working with CSS disappeared. Instead of fighting CSS specificity and trying to debug why a particular style was being overridden and from where within a sea of CSS within components, something changed. CSS flowed, it was easy and best of all, it just worked.

Colors

Perceivable colors that automatically work in both light and dark modes, and that provide sufficient color contrast between foreground and background, are not hard to achieve, especially when each color is separated into a set of colors sharing the same hue, varying only saturation and lightness.

Using human-readable color spaces such as LCH or HSL is preferable to hex codes or RGB because colors can be computed from a given hue. Both are human-readable and fully supported across browsers. I've used both in this theming system across two colors: gray uses HSL, and purple uses LCH. I'm starting to prefer HSL for the many generators available and its ease of readability, which is easier to understand than LCH.

Colors are stored in color files, each of which can define 7 or 12 design tokens that differ mostly in saturation and lightness. Definitions in the color files can be set to automatically change based on a user's light or dark mode preference.

@layer system {
  /*Based off hue 151 */
  :root {
    /*Light Desaturated - Background */
    --raw-purple-1: 96.73% 0.00508 325.62;
    --raw-purple-2: 90.813% 0.02278 321.35;
    --raw-purple-3: 84.919% 0.03759 320.35;

    /* Light Saturated */
    --raw-purple-4: 79.126% 0.0733 320.93;
    --raw-purple-5: 73.236% 0.0934 321.48;
    --raw-purple-6: 67.281% 0.10972 321.13;

    /* Medium */
    --raw-purple-7: 62.241% 0.10499 321.38;

    --raw-purple-8: 55.082% 0.09248 321.86;
    --raw-purple-9: 48.822% 0.08156 321.03;

    /* Dark */
    --raw-purple-10: 42.402% 0.07362 322.08;
    --raw-purple-11: 36.178% 0.06256 322.17;
    --raw-purple-12: 29.673% 0.05099 322.32;

    --purple-1: oklch(var(--raw-purple-1));
    --purple-2: oklch(var(--raw-purple-2));
    --purple-3: oklch(var(--raw-purple-3));
    --purple-4: oklch(var(--raw-purple-4));
    --purple-5: oklch(var(--raw-purple-5));
    --purple-6: oklch(var(--raw-purple-6));
    --purple-7: oklch(var(--raw-purple-7));
    --purple-8: oklch(var(--raw-purple-8));
    --purple-9: oklch(var(--raw-purple-9));
    --purple-10: oklch(var(--raw-purple-10));
    --purple-11: oklch(var(--raw-purple-11));
    --purple-12: oklch(var(--raw-purple-12));
  }

  @media (prefers-color-scheme: dark) {
    :root {
      /*Light Desaturated - Background */
      --raw-purple-12: 96.73% 0.00508 325.62;
      --raw-purple-11: 90.813% 0.02278 321.35;
      --raw-purple-10: 84.919% 0.03759 320.35;

      /* Light Saturated */
      --raw-purple-9: 79.126% 0.0733 320.93;
      --raw-purple-8: 73.236% 0.0934 321.48;
      --raw-purple-7: 67.281% 0.10972 321.13;
      /* Medium */
      --raw-purple-6: 62.241% 0.10499 321.38;

      --raw-purple-5: 55.082% 0.09248 321.86;
      --raw-purple-4: 48.822% 0.08156 321.03;

      /* Dark */
      --raw-purple-3: 42.402% 0.07362 322.08;
      --raw-purple-2: 36.178% 0.06256 322.17;
      --raw-purple-1: 29.673% 0.05099 322.32;
    }
  }
}

GitHub (release 0.2.1) - Theming System - purple.css

The color file for purple, shown above, defines the same colors in both light and dark color schemes as the raw variables, which are then defined using oklch(). This enables an automatic dark color scheme and allows using the --raw variables when opacity needs to be adjusted. My initial foray into this was discovering the custom palettes available through Radix-UI, though I don't use their generator at all.

A color sheet created in this manner also allows for easily achievable color contrast. Formulas for non-vibrant colors achieve color contrast with variables -1 through -4 when paired with any color in the -8 through -12 range. You can see this in a palette color theming system called primer prism.

Design Tokens for Theming

CSS variables are not just for setting colors. They are flexible and mutable, allowing themselves to be set and reset to affect only those elements contained in a selector. Design tokens can be used by base components, tying them into the design system in a way that goes far beyond simple color selection.

<div id="initial">
  <div>
    <div>
      <div></div>
    </div>
  </div>
</div>
<div id="secondary">
  <div>
    <div>
      <button>Hello World</button>
    </div>
  </div>
</div>

Consider the HTML code above. Two series of nested empty divs, with the second series also holding a button in the innermost div.

#initial {
  --theme-background: var(--red-1);
  width: calc(var(--sp-px) * 160);
  & div {
    background-color: var(--theme-background);
    padding: calc(var(--sp-px) * 20);
  }

  > div {
    border: 1px solid var(--theme-border-color);
    & > div {
      --theme-background: var(--purple-2);
      & > div {
        --theme-background: var(--gray-3);
      }
    }
  }
}

The CSS sets the —theme-background token to a light red and applies it to every div in the DOM, along with padding. Using Nested CSS and the descendant selector, I can target the individual divs nested within each other and change the theme background.

#secondary {
  --theme-background: var(--gray-1);
  position: relative;
  left: 25%;
  top: calc(var(--sp-px) * -160);
  margin-top: calc(var(--sp-px) * 20);
  width: calc(var(--sp-px) * 180);

  & div {
    background-color: var(--theme-background);
    padding: calc(var(--sp-px) * 20);
  }
  & > div {
    --theme-background: var(--gray-3);
    & > div {
      --theme-background: var(--red-3);
      & button {
        --button-background: var(--purple-6);
        --button-color: var(--gray-1);
        padding: calc(var(--sp-px) * 20);
      }
    }
  }
}

In the secondary example, a button is targeted by a —button-background token, along with setting the text color to a lighter value.

Variables set at a specific point in the DOM affect only the items contained within it.

Component Theming

The theming I'm using in the repository is pared down to the bare minimum, and isn't the best representation of what it will eventually become. But it's sufficient to demonstrate the power of plain CSS and Structural HTML.

/* Button*/
button {
  /* Common widths and spacing */
  --button-padding: calc(var(--sp-px) * 4) calc(var(--sp-px) * 12);
  --button-border-radius: calc(var(--sp-px) * 8);
  --button-border-width: calc(var(--sp-px) * 2);
  --button-font-size: inherit;
  --button-font-weight: 500;
  --button-line-height: 1.4;
  --button-letter-spacing: normal;

  /* theme - Solid */
  --button-background: var(--purple-2);
  --button-background-disabled: var(--gray-3);
  --button-background-interactive: var(--purple-3);
  --button-background-pressed: var(--purple-4);

  --button-border-color: var(--gray-5);
  --button-border-color-disabled: var(--gray-3);
  --button-border-color-interactive: var(--gray-9);
  --button-border-color-pressed: var(--button-border-color);

  --button-color: var(--gray-12);
  --button-color-disabled: var(--gray-10);
  --button-color-interactive: var(--purple-11);
  --button-color-pressed: var(--gray-11);

  --button-fill: var(--purple-12);
  --button-fill-disabled: var(--button-color-disabled);
  --button-fill-interactive: var(--button-color-interactive);
  --button-fill-pressed: var(--button-color-pressed);

  /* Ghost  */
  --button-ghost-background: transparent;
  --button-ghost-border: transparent;
}

GitHub (release 0.2.1) - component.css

I'm going to use the button component to demonstrate the theming. You'll notice that design tokens have been set up not only for background, border and text colors, but also for states. There are tokens to hold colors for interactive states, including :hover and :focus, and the pressed variables hold changes when the :active state is in place. Because buttons can hold icons, tokens for various fill states are also set.

With the base button tokens defined, it's time to add them to the actual component.

Component Styling

Component stylesheets live in the same folder as their component, and, since I'm using Next.js, are side-loaded into the globals.css file to ensure they are loaded only once. Not every base component needs to include specific styling; where styling is present, it should be generic. Styling for base components is applied in an @layer base-component{element{}} to ensure initial styling is available regardless of where the HTML element is located.

GitHub (release 0.2.1) - button.css

  button {
      /* Layout */
      align-content: center;
      align-items: center;
      display: flex;
      flex-wrap: wrap;
      justify-content: center;
      margin: 0;
      padding: var(--button-padding);
      width: fit-content;
  }

Every button starts with a flex layout that centers its content and initially sets its width to fit the content. Padding is wired in through the button-padding token since that can and will be changed regularly.

button {   /* continued */
  /* Text */
  font-size: var(--button-font-size);
  font-weight: var(--button-font-weight);
  letter-spacing: var(--button-letter-spacing);
  line-height: var(--button-line-height);
  text-decoration: none;

  /* Appearance */
  border-radius: var(--button-border-radius);
  border-style: solid;
  border-width: var(--button-border-width);
  cursor: pointer;
}

Text and appearance depend on more tokens, which can be overridden wherever necessary.

button {   /* continued */
/* Colors */
--svg-color: var(--button-color);
--svg-fill: var(--button-fill);

background-color: var(--button-background);
border-color: var(--button-border-color);
color: var(--button-color);  }

All colors associated with the button are set to the tokens by default. Either the background-color or the token may be overridden.

button {   /* continued */
    /* States - */
    &[aria-disabled="true"] {
      --button-background: var(--button-background-disabled);
      --button-border-color: var(--button-border-color-disabled);
      --button-color: var(--button-color-disabled);
      --svg-color: var(--button-color-disabled);
      --svg-fill: var(--button-fill-disabled);

      cursor: default;
    }

    &:focus-visible {
      outline: var(--focus-outline) var(--focus-outline-color);
      outline-offset: var(--focus-outline-offset);
    }
    &:focus,
    :hover {
      --button-background: var(--button-background-interactive);
      --button-border-color: var(--button-border-color-interactive);
      --button-color: var(--button-color-interactive);
      --svg-color: var(--button-color-interactive);
      --svg-fill: var(--button-fill-interactive);
    }
  }

When it comes to state changes, I prefer to style them using either aria- attributes or pseudo-classes such as :focus and :hover. Styling on aria- attributes reinforces accessibility. If the aria- attribute is required, why not style it through the attribute rather than adding in yet another class that needs to be deciphered?

In the article Foundational Accessibility Begins with the Base Components, I explained how the disabled attribute causes issues with screen readers and proposed a fix that used aria-disabled instead. The styles around the aria-disabled attribute are the last aspect necessary. Note how every line in the rule simply replaces the original token with one based on a disabled state. That's all that is necessary. It's the same with the focus and hover pseudo-classes.

Box-Sizing with Border-Box

My sanitization scripts apply the box-sizing: border-box rule to every element. This box-sizing rule defines the width and height to include content, padding, and borders. I've found this rule makes it easier to work with positioning and layout, since a component's width and height remain constant regardless of padding or borders.

When using "border-box", note that changing from "border: none" to "border: solid" or adjusting the border-width during a state change will shift the component's content. My solution is to set the border width in advance and use "color: transparent" to emulate a no-border effect. In this scenario, a user sees a borderless box since the transparent border sits on top of the background. During a state change, there is no shifting, since the border simply swaps colors. Make sure the border-width remains consistent.

Summary

Adding a theming system doesn't have to be complicated or require another package. Regardless of the theming system you use, wiring the components that render to HTML into your system will save a lot of time and headaches down the road.

With the base components added in and connected to the theming systems, the next step will be to create the actual components of the Navigation system.