@pras-ui/popup-menu

A headless, accessible, and highly customizable multi purpose component(popup menu, context menu) for React.

@pras-ui/popup-menu provides the building blocks to create fully-featured popup menu. It handles all the complex logic, like state management, keyboard navigation, accessibility, and positioning, leaving you to focus on styling.

Features

• Headless & Unstyled: Gives you full control over the appearance.
• Full Keyboard Navigation: Arrow key navigation and shortcuts are supported out of the box.
• Context Menu Mode: Can be triggered by right-clicking.
• Sub-menus: Supports infinitely nested sub-menus.
• Choice Items: Create radio groups or checkbox groups inside your menu.
• RTL Support: Adapts automatically to right-to-left languages.
• Accessible: Follows WAI-ARIA patterns for menus.

Installation

npm install @pras-ui/popup-menu

Usage

Here's how to create a basic popup menu. You can use any styling solution you prefer; this example uses simple class names.

import {
  PopupMenuRoot,
  PopupMenuTrigger,
  PopupMenuContent,
  PopupMenuItem,
  PopupMenuPortal,
} from "@pras-ui/popup-menu";

function MyPopupMenu() {
  return (
    <PopupMenuRoot>
      <PopupMenuTrigger asChild>
        <button className="my-trigger-button">Open Menu</button>
      </PopupMenuTrigger>

      <PopupMenuPortal>
        <PopupMenuContent className="my-menu-content" sideOffset={5}>
          <PopupMenuItem
            className="my-menu-item"
            onSelect={() => alert("New Tab")}
          >
            New Tab
          </PopupMenuItem>
          <PopupMenuItem
            className="my-menu-item"
            onSelect={() => alert("New Window")}
          >
            New Window
          </PopupMenuItem>
          <PopupMenuItem className="my-menu-item" disabled>
            New Incognito Window
          </PopupMenuItem>
        </PopupMenuContent>
      </PopupMenuPortal>
    </PopupMenuRoot>
  );
}

API Reference

PopupMenuRoot

| Prop | Type | Default | Description | | -------------- | ------------------------- | ----------- | ------------------------------------------------- | | open | boolean | | The controlled open state of the menu. | | defaultOpen | boolean | false | The initial open state when uncontrolled. | | onOpenChange | (open: boolean) => void | | Event handler called when the open state changes. | | mode | 'default' \| 'context' | 'default' | 'context' mode enables right-click triggering. | | dir | 'ltr' \| 'rtl' | (inherited) | The reading direction of the menu. |

PopupMenuTrigger

The button or element that toggles the menu. It should be a direct child of PopupMenuRoot. It accepts all props of a standard button element.

| Attributes | Type | Description | | --------------- | ------------------- | ----------------------------- | | data-hovered | true \| undefined | Whether the item is hovered. | | data-focused | true \| undefined | Whether the item is focused. | | data-disabled | true \| undefined | Whether the item is disabled. | | data-state | opened \| closed | The open state of the menu. |

PopupMenuPortal

Renders the menu content into a React Portal, ensuring it can overlay other elements. This is recommended to avoid z-index and clipping issues.

PopupMenuContent

| Prop | Type | Default | Description | | ------------------------- | ---------------------------------------- | ----------- | ------------------------------------------------------------------------ | | dir | 'ltr' \| 'rtl' | (inherited) | The reading direction of the menu. | | side | 'top' \| 'bottom' \| 'left' \| 'right' | 'bottom' | The preferred side of the trigger to render the content on. | | sideOffset | number | 0 | The distance in pixels from the trigger. | | align | 'start' \| 'center' \| 'end' | 'start' | The preferred alignment of the content relative to the trigger. | | alignOffset | number | 0 | The distance in pixels from the trigger. | | collisionBoundary | Boundary \| Boundary[] | | The boundary of the floating element. | | collisionPadding | number \| Record<Side, number> | 0 | The padding of the floating element. | | sticky | 'partial' \| 'always' | 'partial' | Whether to sticky the floating element. | | autoHideOnDetach | boolean | false | Whether to auto hide the floating element on detach. | | removeScroll | boolean | true | Whether to remove scroll on the floating element. | | position | 'absolute' \| 'fixed' | 'fixed' | The position of the floating element. | | updatePositionFrequency | 'lazy' \| 'rapid' | 'lazy' | The frequency of the floating element position update. | | alwaysRender | boolean | false | Whether to always render the floating element. | | loop | boolean | true | Whether keyboard navigation should loop around. | | avoidCollisions | boolean | true | Whether to prevent the content from overlapping with the viewport edges. | | closeOnScroll | boolean | true | Whether the menu should close when scrolling outside of it. | | navigationUp | Keys[] \| Keys[][] | [] | Custom key(s) to trigger upward navigation through menu items. | | navigationDown | Keys[] \| Keys[][] | [] | Custom key(s) to trigger downward navigation through menu items. | | onEsc | (e: Event) => void | | event handler for the Escape key press. | | onOutsideInteraction | (e: Event) => void | | event handler for clicks or focus outside the menu. |

| Attributes | Type | Description | | ------------ | ------------------ | --------------------------- | | data-state | opened \| closed | The open state of the menu. |

PopupMenuItem

| Prop | Type | Default | Description | | -------------- | --------------------------------- | ------- | --------------------------------------------------------------------- | | disabled | boolean | false | Prevents the item from being selected. | | onClick | (e: MenuItemClickEvent) => void | | Event handler called when the item is selected via click or keyboard. | | closeOnClick | boolean | true | Whether the menu should close after the item is selected. |

| Attributes | Type | Description | | --------------- | ------------------- | ----------------------------- | | data-hovered | true \| undefined | Whether the item is hovered. | | data-focused | true \| undefined | Whether the item is focused. | | data-disabled | true \| undefined | Whether the item is disabled. |

PopupSubMenuRoot

| Prop | Type | Default | Description | | -------------- | ------------------------------ | -------- | ------------------------------------------------------------- | | open | boolean | | The controlled open state of the sub-menu. | | defaultOpen | boolean | false | The initial open state when uncontrolled. | | onOpenChange | (open: boolean) => void | | Event handler called when the open state changes. | | openStrategy | 'hover' \| 'click' \| 'both' | 'both' | How the sub-menu should be triggered. | | delay | number | 0 | The delay in milliseconds before the sub-menu opens on hover. |

PopupSubMenuTrigger

| Prop | Type | Default | Description | | ---------- | --------------------------------- | ------- | --------------------------------------------------------------------- | | disabled | boolean | false | Prevents the item from being selected. | | onClick | (e: MenuItemClickEvent) => void | | Event handler called when the item is selected via click or keyboard. |

| Attributes | Type | Description | | --------------- | ------------------- | ----------------------------- | | data-hovered | true \| undefined | Whether the item is hovered. | | data-focused | true \| undefined | Whether the item is focused. | | data-disabled | true \| undefined | Whether the item is disabled. |

PopupSubMenuContent

The positioned container for the sub-menu's items. It has the same props as PopupMenuContent.

PopupMenuChoice

Used to group a set of PopupMenuChoiceItem components.

| Prop | Type | Default | Description | | -------------- | ------------------------------------- | ---------- | ---------------------------------------------------- | | mode | 'single' \| 'multiple' | 'single' | Determines if one or multiple items can be selected. | | defaultValue | string \| string[] | | The initial value when uncontrolled. | | onChange | (value: string \| string[]) => void | | Event handler called when the value changes. |

PopupMenuChoiceItem

A selectable item within a PopupMenuChoice group.

| Prop | Type | Description | | ------- | -------- | -------------------------------------------------------- | | value | string | The value of the item, used to identify it in the group. |

| Attribute | Type | Description | | ------------ | ------------------------ | ---------------------- | | data-state | selected \| unselected | The state of the item. |

PopupMenuChoiceIndicator

A component that displays a checkmark or other icon when its parent PopupMenuChoiceItem is selected. It will be hidden otherwise.

| Attribute | Type | Description | | ------------ | ------------------------ | ---------------------- | | data-state | selected \| unselected | The state of the item. |

Other Components

• PopupMenuArrow: An optional arrow component that can be placed inside PopupMenuContent to point towards the trigger.
• PopupMenuGroup: A utility component to visually group items together.
• PopupMenuLabel: A non-interactive label for a PopupMenuGroup.