Menu

WAI-ARIA compliant menu (menu button) pattern implementation in TypeScript. Supports checkbox item, radio item, and infinitely nested menus.

Install

npm i @y14e/menu

// npm
import Menu from '@y14e/[email protected]';
// with middleware
import Menu, { flip, offset, shift } from '@y14e/[email protected]';

// CDNs
import Menu from 'https://esm.sh/@y14e/[email protected]';
// or
import Menu from 'https://cdn.jsdelivr.net/npm/@y14e/[email protected]/+esm';
// or
import Menu from 'https://esm.unpkg.com/@y14e/[email protected]';

Usage

new Menu(root, options);
// => Menu
//
// root: HTMLElement
// options (optional): MenuOptions

🪄 Options

interface MenuOptions {
  animation?: {
    duration?: number;         // ms (default: 300)
  };
  delay?: number;              // ms (default: 200)
  onBlurWithin?: (menu: Menu, next: HTMLElement | null, wasOpen: boolean) => void
  onClose?: (menu: Menu, reason: MenuCloseReason) => void
  onFocusWithin?: (menu: Menu, previous: HTMLElement | null) => void
  popover?: {
    menu?: MenuPopoverOptions;
    submenu?: MenuPopoverOptions;
    transformOrigin?: boolean; // default: true
  };
  selector?: {
    checkboxItem?: string;     // default: '[role="menuitemcheckbox"]'
    group?: string;            // default: '[role="group"]'
    item?: string;             // default: '[role^="menuitem"]'
    list?: string;             // default: '[role="menu"]'
    radioItem?: string;        // default: '[role="menuitemradio"]'
    trigger?: string;          // default: '[data-menu-trigger]'
  };
}

type MenuCloseReason = 'escape' | 'outside' | 'shift-tab' | 'tab' | 'trigger' | undefined;

interface MenuPopoverOptions {
  arrow?: boolean;             // default: true
  middleware?: Middleware[];   // default: [flip(), offset(), shift()]
  placement?: Placement;       // default: 'bottom-start' (menu) / 'right-start' (submenu)
}

[!NOTE] Middleware and Placement are provided by Floating UI. See the Floating UI docs for details.

⚙️ Customize defaults

Override the global default settings applied to all menu instances.

import Menu from '@y14e/menu';

Menu.defaults = {
  delay: 500,
  selector: {
    trigger: '.trigger',
  },
};

new Menu(root);

📦 APIs

close

menu.close();
// => void

destroy

Destroys the instance and cleans up all event listeners and submenus.

menu.destroy(force);
// => Promise<void>
//
// force (optional): If true, skips waiting for animations to finish.

isOpen

menu.isOpen();
// => boolean

open

menu.open();
// => void

Demo

https://y14e.github.io/menu/

Credits

• Floating UI