@jldust/accessible-menu

Highly configurable, accessible menu components that support keyboard navigation, mobile controls, and ARIA attributes.

Current Support

This library implements the AdvancedMenu pattern (based on the WAI-ARIA menubar pattern) and the SimpleMenu navigation pattern (based on the WAI-ARIA disclosure pattern) from the WAI-ARIA Authoring Practices Guide.

Future Plans

We have plans to support additional menu patterns, including:

• Tree menu pattern
• And more to come

Features

• Keyboard Navigation: Full arrow key support, tab navigation, and escape key handling
• Mobile-First: Responsive design with configurable breakpoints
• ARIA Compliant: Proper ARIA attributes for screen readers
• Configurable: Customize CSS classes, breakpoints, and behavior
• Framework Agnostic: Works with any framework or vanilla JavaScript
• TypeScript Support: Full type definitions included

Installation

npm install @jldust/accessible-menu

Basic Usage

ES6 Modules

import { AdvancedMenu } from '@jldust/accessible-menu'

// Initialize with default settings
const menu = new AdvancedMenu()
await menu.init()

With CSS Styles

<!-- Include the CSS for menu styling -->
<link rel="stylesheet" href="node_modules/@jldust/accessible-menu/dist/menu-styles.css" />

<!-- Or import in your CSS/SCSS -->
@import '~@jldust/accessible-menu/dist/menu-styles.css';

import { AdvancedMenu } from '@jldust/accessible-menu'

const menu = new AdvancedMenu()
await menu.init()

CommonJS

const { AdvancedMenu } = require('@jldust/accessible-menu')

const menu = new AdvancedMenu()
await menu.init()

UMD (Browser)

<script src="node_modules/@jldust/accessible-menu/dist/index.umd.min.js"></script>
<script>
  const menu = new AccessibleMenu.AdvancedMenu()
  await menu.init()
</script>

SimpleMenu Navigation

Use SimpleMenu for simple navigation menus. It does not add menu roles, manage tabindex, or include support mega-menu behavior. Mobile navigation is enabled by providing mobileControlId.

<button id="mobile-toggle" aria-expanded="false">Menu</button>
<nav class="c-menu" aria-label="Primary navigation">
  <ul class="menu" data-depth="0">
    <li class="menu__item"><a class="menu__link" href="/">Home</a></li>
    <li class="menu__item">
      <button class="menu__button">Products</button>
      <ul class="menu">
        <li class="menu__item"><a class="menu__link" href="/products/one">Product one</a></li>
        <li class="menu__item"><a class="menu__link" href="/products/two">Product two</a></li>
      </ul>
    </li>
  </ul>
</nav>

import { SimpleMenu } from '@jldust/accessible-menu'

const navigation = new SimpleMenu({
  mobileControlId: 'mobile-toggle',
  mobileBreakpoint: 768,
})
await navigation.init()

SimpleMenu buttons must be button elements followed immediately by the panel they control. Initialization sets aria-controls, aria-expanded="false", and the configured controller class. Existing panel IDs are preserved; missing IDs are generated.

| Option | Type | Default | | ------------------------- | ---------------- | ------------------- | | menuSelector | string | 'c-menu' | | buttonClass | string | 'menu__button' | | linkClass | string | 'menu__link' | | controllerClass | string | 'controller' | | menuContainer | string \| null | null | | mobileBreakpoint | number | 768 | | mobileControlId | string \| null | null | | dataBreakpointAttribute | string | 'data-breakpoint' |

The mobile toggle must provide its initial aria-expanded="false" state. An authored data-breakpoint value on the navigation root overrides mobileBreakpoint. Closing the mobile navigation also closes its open disclosure panels.

SimpleMenu Keyboard Support

| Key | Action | | ---------------------- | ------------------------------------------------------------------------------------------------- | | Tab / Shift + Tab | Uses native document order through buttons and links in expanded panels | | Enter / Space | Toggles a focused button; activates a link and sets its aria-current="page" | | Escape | Closes the nearest open dropdown and returns focus to its controlling button | | Arrow Down / Right | Moves forward among top-level links and buttons or panel links; enters an expanded button's panel | | Arrow Up / Left | Moves backward among top-level links and buttons or panel links | | Home / End | Moves to the first or last link or button in the current level |

Directional navigation does not wrap. Nested disclosure buttons support native Tab, Enter/Space, Escape, peer closing, and descendant closing; optional arrow, Home, and End behavior for nested buttons is intentionally not included.

Opening a disclosure closes open peers at the same level. Open disclosures also close when focus leaves the navigation or a pointer interaction starts outside it. Use destroy(menuContainer) or destroyAll() to remove behavior.

Configuration

Custom Configuration

import { AdvancedMenu } from '@jldust/accessible-menu'

const menu = new AdvancedMenu({
  menuSelector: 'my-menu',
  buttonClass: 'my-menu__button',
  linkClass: 'my-menu__link',
  itemClass: 'my-menu__item',
  mobileBreakpoint: 1024,
  mobileControlId: 'mobile-menu-toggle',
})

await menu.init()

Configuration Options

| Option | Type | Default | Description | | ------------------------ | ---------------- | ------------------- | --------------------------------------------------------------------- | | menuSelector | string | 'c-menu' | CSS selector for menu containers | | menuContainer | string | 'site-header' | CSS selector for entire container | | buttonClass | string | 'menu__link' | CSS class for menu buttons | | labelClass | string | 'menu__label' | CSS class for menu labels | | linkClass | string | 'menu__link' | CSS class for menu links | | itemClass | string | 'menu__item' | CSS class for menu items | | megaMenu | boolean | false | Enables mega menu support | | megaMenuContainerClass | string | 'menu__container' | CSS class for mega menu dropdown containers | | mobileBreakpoint | number | 768 | Mobile breakpoint in pixels | | mobileControlId | string \| null | 'nav-toggle' | ID of the mobile menu control button, when set enables mobile support |

HTML Structure

Basic Menu Structure

<nav class="c-menu" data-breakpoint="768">
  <ul class="menu" data-depth="0">
    <li class="menu__item">
      <a href="#" class="menu__link">Home</a>
    </li>
    <li class="menu__item menu__item--expanded">
      <button class="menu__link">About</button>
      <ul class="menu" data-depth="1">
        <li class="menu__item">
          <a href="#" class="menu__link">Our Story</a>
        </li>
        <li class="menu__item">
          <a href="#" class="menu__link">Team</a>
        </li>
      </ul>
    </li>
  </ul>
</nav>

<!-- Mobile toggle button -->
<button id="mobile-toggle" aria-expanded="false">Menu</button>

Mega Menu Structure (Work In Progress)

<nav class="c-menu">
  <ul class="menu" data-depth="0">
    <li class="menu__item menu__item--expanded">
      <span class="menu__link">Services</span>
      <div class="c-mega-menu__wrapper">
        <ul class="menu" data-depth="1">
          <li class="menu__item">
            <a href="#" class="menu__link">Web Design</a>
          </li>
          <li class="menu__item">
            <a href="#" class="menu__link">Development</a>
          </li>
        </ul>
      </div>
    </li>
  </ul>
</nav>

Keyboard Navigation

| Key | Action | | ------------------------- | ---------------------------------------------------- | | Arrow Down / Arrow Up | Navigate between menu items vertically | | Arrow Right | Open submenu or navigate to next top-level item | | Arrow Left | Close submenu or navigate to previous top-level item | | Tab | Navigate to next focusable element | | Escape | Close current submenu and return focus to parent | | Enter / Space | Activate menu button or follow link |

Mobile Behavior

• Menu collapses below the configured breakpoint
• Mobile toggle button controls menu visibility
• Clicking outside the menu closes it on mobile
• Escape key closes the mobile menu
• Body scroll is prevented when mobile menu is open

API Methods

init(context)

Initialize menus within the specified context.

// Initialize all menus on the page
menu.init()

// Initialize menus within a specific container
menu.init(document.querySelector('.header'))

destroy(menuContainer)

Destroy a specific menu instance.

const menuElement = document.querySelector('.c-menu')
menu.destroy(menuElement)

destroyAll()

Destroy all menu instances.

menu.destroyAll()

CSS Styles

The package includes pre-built CSS styles that handle menu open/close animations and basic layout:

Including CSS Styles

<!-- Include the CSS file -->
<link rel="stylesheet" href="node_modules/@jldust/accessible-menu/dist/menu-styles.css" />

/* Or import in your CSS/SCSS */
@import '~@jldust/accessible-menu/dist/menu-styles.css';

Key CSS Features

• Smooth animations for menu open/close with opacity and transform transitions
• Mobile-responsive layout with hamburger menu behavior
• Focus indicators for keyboard navigation
• ARIA-based styling that responds to aria-expanded attributes
• Customizable - override styles as needed for your design system

Critical CSS Selectors

The CSS relies on these key selectors for functionality:

/* Hidden state */
.controller[aria-expanded='false'] + *:not([data-depth='0']) {
  opacity: 0;
  visibility: hidden;
  transform: translateY(-10px);
}

/* Visible state */
.controller[aria-expanded='true'] + *:not([data-depth='0']) {
  opacity: 1;
  visibility: visible;
  transform: translateY(0);
}

Dependencies

No external dependencies! The package is completely self-contained.

Development

Building the Package

npm run build

Development Mode

npm run dev

Running Tests

npm test

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see the LICENSE file for details.

Accessibility

To the best of our ability this library follows WCAG 2.2 AA guidelines and implements WAI-ARIA best practices for navigation menus. It has been tested with macOS VoiceOver and keyboard-only navigation.

Changelog

1.0.0

• Initial release
• Full keyboard navigation support
• Mobile menu controls
• ARIA compliance
• TypeScript definitions