Kappa / Context Menu

<script setup lang="ts">
import {
  ContextMenu,
  type ContextMenuSelectionDetails,
} from "@dicehub/kappa/components/context-menu";

const handleAction = (details: ContextMenuSelectionDetails) => {
  console.log(details.value);
};
</script>

<template>
  <ContextMenu.Root aria-label="Run actions" @select="handleAction">
    <ContextMenu.Trigger class="run-row">
      Run 4189
    </ContextMenu.Trigger>
    <ContextMenu.Content>
      <ContextMenu.Item value="open">Open results</ContextMenu.Item>
      <ContextMenu.Item value="copy">Copy run ID</ContextMenu.Item>
      <ContextMenu.Separator />
      <ContextMenu.Item value="delete" variant="destructive">
        Delete run
      </ContextMenu.Item>
    </ContextMenu.Content>
  </ContextMenu.Root>
</template>

Installation

Context Menu uses the same Ark UI menu behavior and Kappa styling as Dropdown. It provides a dedicated trigger for secondary actions without creating a second menu implementation.

Barrel

import {
  ContextMenu,
  type ContextMenuSelectionDetails,
} from "@dicehub/kappa";

Granular

import {
  ContextMenu,
  type ContextMenuSelectionDetails,
} from "@dicehub/kappa/components/context-menu";

Usage

Wrap one focusable target with Trigger. Use a unique value for every item. Handle commands from the root select event.

Right-click opens the menu at the pointer.
Shift+F10 or the Context Menu key opens it from the focused target.
Touch and pen input use the long-press behavior supplied by Ark UI.

Composition

Typical part hierarchy

ContextMenu.Root
├── ContextMenu.Trigger (pointer and keyboard target)
└── ContextMenu.Content
    ├── ContextMenu.Group
    │   ├── ContextMenu.Label
    │   ├── ContextMenu.Item
    │   ├── ContextMenu.CheckboxItem
    │   └── ContextMenu.RadioGroup
    │       └── ContextMenu.RadioItem
    ├── ContextMenu.Separator
    └── ContextMenu.Sub
        ├── ContextMenu.SubTrigger
        └── ContextMenu.SubContent

ContextMenu.Trigger is the context-trigger counterpart of Dropdown.Trigger. The other parts share Kappa's menu behavior, styles, item variants, and state contracts.

Use as-child when an existing button, row, or tree item must remain the semantic target.
Use LinkItem for navigation. Do not put a link inside Item.
Use Sub sparingly. Deep secondary navigation is difficult with pointer and touch input.
Keep primary actions visible. A context menu is an additional route, not the only route, to important commands.

Examples

Resource List

Give each resource its own menu so selection stays tied to the correct target.

<ContextMenu.Root
  v-for="resource in resources"
  :key="resource.id"
  :aria-label="`${resource.name} actions`"
  @select="handleResourceAction(resource, $event.value)"
>
  <ContextMenu.Trigger as-child>
    <button type="button" class="resource-row">
      {{ resource.name }}
    </button>
  </ContextMenu.Trigger>
  <ContextMenu.Content>
    <ContextMenu.Item value="open">Open</ContextMenu.Item>
    <ContextMenu.Item value="rename">Rename</ContextMenu.Item>
    <ContextMenu.Item value="copy-path">Copy path</ContextMenu.Item>
  </ContextMenu.Content>
</ContextMenu.Root>

Tree View

Compose the trigger around each tree item or branch control so file actions stay available by pointer and keyboard.

<TreeView.Root
  :collection="collection"
  :default-expanded-value="['case']"
>
  <TreeView.Tree>
    <TreeView.NodeProvider
      v-for="(node, index) in files"
      :key="node.value"
      :node="node"
      :index-path="[index]"
    >
      <ContextMenu.Root :aria-label="`${node.label} actions`">
        <ContextMenu.Trigger as-child>
          <TreeView.Item>
            <TreeView.ItemText>{{ node.label }}</TreeView.ItemText>
          </TreeView.Item>
        </ContextMenu.Trigger>
        <ContextMenu.Content>
          <ContextMenu.Item value="open">Open</ContextMenu.Item>
          <ContextMenu.Item value="rename">Rename</ContextMenu.Item>
          <ContextMenu.Item value="copy-path">Copy path</ContextMenu.Item>
        </ContextMenu.Content>
      </ContextMenu.Root>
    </TreeView.NodeProvider>
  </TreeView.Tree>
</TreeView.Root>

Nested Actions

Use a submenu when an action needs a short second choice.

<ContextMenu.Root aria-label="Mesh file actions">
  <ContextMenu.Trigger class="file-target">mesh.foam</ContextMenu.Trigger>
  <ContextMenu.Content>
    <ContextMenu.Item value="open">Open</ContextMenu.Item>
    <ContextMenu.Sub aria-label="Move destination">
      <ContextMenu.SubTrigger>Move to</ContextMenu.SubTrigger>
      <ContextMenu.SubContent>
        <ContextMenu.Item value="geometry">Geometry</ContextMenu.Item>
        <ContextMenu.Item value="results">Results</ContextMenu.Item>
      </ContextMenu.SubContent>
    </ContextMenu.Sub>
  </ContextMenu.Content>
</ContextMenu.Root>

Persistent Options

Checkbox and radio items remain open while related options change.

<ContextMenu.Root aria-label="Tree view options">
  <ContextMenu.Trigger class="tree-target">Project files</ContextMenu.Trigger>
  <ContextMenu.Content>
    <ContextMenu.Group>
      <ContextMenu.Label>View</ContextMenu.Label>
      <ContextMenu.CheckboxItem v-model:checked="showHidden" value="hidden">
        Show hidden files
      </ContextMenu.CheckboxItem>
    </ContextMenu.Group>
    <ContextMenu.RadioGroup v-model="density">
      <ContextMenu.Label>Density</ContextMenu.Label>
      <ContextMenu.RadioItem value="compact">Compact</ContextMenu.RadioItem>
      <ContextMenu.RadioItem value="comfortable">Comfortable</ContextMenu.RadioItem>
    </ContextMenu.RadioGroup>
  </ContextMenu.Content>
</ContextMenu.Root>

Accessibility

The trigger must be keyboard focusable and have a clear accessible name.
Arrow keys move the active item. Home and End move to the first or last enabled item.
Escape closes the menu. A keyboard-opened menu restores focus to its trigger.
Disabled items remain visible but are skipped by keyboard navigation.
Item labels must describe the action without depending on an icon.

See the official Ark UI Menu documentation for the complete behavior contract.

API Reference

ContextMenu.Root

Prop	Type	Default	Description
`ariaLabel`	`string`	`—`	Accessible name mirrored to the menu surface.
`open / defaultOpen`	`boolean`	`false`	Controlled or initial open state.
`highlightedValue / defaultHighlightedValue`	`string`	`—`	Controlled or initial highlighted item.
`closeOnSelect`	`boolean`	`true`	Closes the menu after a normal item is selected.
`dir`	`"ltr" \| "rtl"`	`inherited`	Reading direction for placement and keyboard behavior.
`positioning`	`PositioningOptions`	`fixed cursor anchor`	Collision and viewport positioning options.

Parts

Part	Element	Description
`ContextMenu.Root / RootProvider`	`none`	Owns open, highlight, selection, and positioning state.
`ContextMenu.Trigger`	`button`	Opens at the pointer, or near the target with Shift+F10 or the Context Menu key.
`ContextMenu.Content`	`div`	Portalled menu surface positioned at the interaction point.
`ContextMenu.Item / LinkItem`	`div / a`	Action and navigation menu items.
`ContextMenu.CheckboxItem`	`div`	Boolean option that stays open by default.
`ContextMenu.RadioGroup / RadioItem`	`div`	Single-choice option group.
`ContextMenu.Group / Label / Separator`	`div`	Menu structure and visible grouping.
`ContextMenu.Sub / SubTrigger / SubContent`	`mixed`	Nested context actions with pointer-intent handling.
`ContextMenu.Shortcut`	`span`	Visual keyboard hint. It does not register a shortcut.

Events

Event	Payload	Description
`select`	`ContextMenuSelectionDetails`	An item was selected; details.value identifies it.
`openChange / update:open`	`details / boolean`	The menu opened or closed.
`highlightChange`	`ContextMenuHighlightChangeDetails`	The roving highlight changed.
`escapeKeyDown`	`KeyboardEvent`	Escape was pressed while the menu was open.
`interactOutside`	`ContextMenuInteractOutsideEvent`	Pointer or focus input occurred outside the menu.

Exports

Export	Description
`ContextMenu / ContextMenuRoot`	Compound root and named root export.
`ContextMenuTrigger / Content / Item / Sub*`	Named exports for compound parts.
`ContextMenuProps / ContextMenu*Props`	Public root and part contracts.
`CONTEXT_MENU_ITEM_VARIANTS`	Default and destructive item variants.
`CONTEXT_MENU_DEFAULT_POSITIONING`	Fixed viewport positioning defaults for pointer-anchored menus.
`useContextMenu / useContextMenuContext`	Ark UI menu hooks under Context Menu names.
`contextMenuAnatomy`	Ark UI menu anatomy under the Context Menu name.

Case files