Context Menu

A primitive for building context menus that open at the pointer position on right-click (or long-press on touch devices). Use ContextMenu when you need a menu bound to a region rather than a visible trigger button.

import { ContextMenu } from "@areia/slots";

document.querySelector("#root")!.innerHTML = `
  <div data-slot="context-menu">
    <div data-slot="context-menu-trigger" class="win95-inset p-3 w-48 select-none text-center">
      Right click here
    </div>
    <div data-slot="context-menu-content" class="win95-menu">
      <div data-slot="context-menu-label" class="win95-label">Actions</div>
      <button data-slot="context-menu-item" data-value="copy" class="win95-menu-item">
        Copy
      </button>
      <button data-slot="context-menu-item" data-value="paste" class="win95-menu-item">
        Paste
      </button>
      <div data-slot="context-menu-separator" class="win95-separator"></div>
      <button
        data-slot="context-menu-item"
        data-value="delete"
        data-variant="destructive"
        class="win95-menu-item">
        Delete
      </button>
    </div>
  </div>
`;

const root = document.querySelector<HTMLElement>(
  '[data-slot="context-menu"]',
)!;
if (root) {
  const controller = ContextMenu.createContextMenu(root, {
    onSelect: (value) => console.log("selected", value),
  });
}

Import

import { ContextMenu } from "@areia/slots";

Usage

Call createContextMenu with the root element and optional configuration. The primitive reads slot attributes from the DOM and manages open/close, item highlight, keyboard navigation, and selection.

import { ContextMenu } from "@areia/slots";

const el = document.querySelector<HTMLElement>(
  '[data-slot="context-menu"]',
)!;
if (!el) throw new Error("No root element found");

const controller = ContextMenu.createContextMenu(el, {
  onOpenChange: (open) => console.log("open changed", open),
  onSelect: (value) => console.log("selected", value),
});

// Programmatic control
controller.open({ x: 200, y: 100 });
// controller.close();
// controller.destroy();

Auto-bind

Use the create helper to discover and bind every unattached root in a scope.

import { ContextMenu } from "@areia/slots";

const controllers = ContextMenu.create(document);
// controllers.forEach((c) => { ... });

Expected Markup

The primitive expects the following slot structure. Every slot attribute must be present for the controller to wire up correctly.

<div data-slot="context-menu">
  <div data-slot="context-menu-trigger">
    <!-- Region that accepts right-click / long-press -->
  </div>

  <div data-slot="context-menu-content">
    <div data-slot="context-menu-label">Actions</div>

    <button data-slot="context-menu-item" data-value="copy">
      Copy
    </button>
    <button data-slot="context-menu-item" data-value="paste">
      Paste
    </button>

    <div data-slot="context-menu-separator"></div>

    <button
      data-slot="context-menu-item"
      data-value="delete"
      data-variant="destructive"
    >
      Delete
    </button>

    <button
      data-slot="context-menu-item"
      data-value="disabled"
      data-disabled
    >
      Disabled
    </button>

    <button
      data-slot="context-menu-checkbox-item"
      data-value="show-hidden"
    >
      Show hidden
    </button>

    <button
      data-slot="context-menu-radio-item"
      data-value="option-a"
    >
      Option A
    </button>
  </div>
</div>

Slot Reference

Data Attributes

The controller manages these state attributes on the root:

Items receive the following state attributes:

Events

All events bubble from the root element (data-slot="context-menu").

Outbound

context-menu:open-change

interface ContextMenuOpenChangeDetail {
  open: boolean;
  previousOpen: boolean;
  source: "pointer" | "keyboard" | "programmatic";
  reason:
    | "trigger"
    | "select"
    | "outside"
    | "escape"
    | "tab"
    | "programmatic";
}

context-menu:select

interface ContextMenuSelectDetail {
  value: string;
  item: HTMLElement;
  itemType: "item" | "radio" | "checkbox";
  source: "pointer" | "keyboard";
  checked?: boolean;
}

API Reference

Options

ContextMenu.createContextMenu(root, options)

Options can also be set via data-* attributes on the root element, using kebab-case names (e.g. data-close-on-select="false"). JS options take precedence over data attributes.

Controller

Controller

The controller is the imperative handle returned by createContextMenu. Use it for programmatic control in response to application state changes, or when you need to open the menu outside of a right-click interaction.

import { ContextMenu } from "@areia/slots";

const el = document.querySelector<HTMLElement>(
  '[data-slot="context-menu"]',
)!;
if (!el) throw new Error("No root element");

const ctrl = ContextMenu.createContextMenu(el, {
  onSelect: (v) => console.log(v),
});

// Read state
console.log(ctrl.isOpen); // boolean
console.log(ctrl.highlightedValue); // string | null

// Open at a specific position
ctrl.open({ x: 300, y: 150 });

// Open at the last known pointer position
ctrl.open();

// Close
ctrl.close();

// Set open state with coordinates
ctrl.setOpen(true, { x: 500, y: 200 });
ctrl.setOpen(false);

// Tear down all listeners
ctrl.destroy();