ContextMenu
A right-click menu that opens at the mouse position within its wrapped region.
Basic usage
Trigger on right-click
Disabled items
Disabled items
Nested submenu
Nested submenu
Items with children expand cascading submenus on hover/click; selecting a leaf item collapses them and closes the menu.
Selection event
Selection event
Programmatic positioning & controlled open
show(x, y) / close()
show(x, y) opens the menu at any coordinates (table rows / canvas / text-selection right-click), close() closes it programmatically; the open attribute controls visibility, and oas-open-change reports the open/close state.
Long-press trigger (mobile)
Mobile devices have no right-click; a long press (500ms by default) opens the menu. long-press-delay adjusts the duration in milliseconds. Verify with DevTools device emulation on desktop.
Long-press trigger
Close on scroll
The menu is fixed-positioned; scrolling the page or an inner scroll container closes it by default (so it never detaches from the content). Set close-on-scroll="false" to disable.
Close on scroll
Declarative child-element channel
Besides the items JSON, you can declare the menu with <oas-context-menu-item> / <oas-context-menu-group> / <oas-context-menu-divider> child elements (the items attribute wins when set explicitly; otherwise children are parsed and converge to the same rendering path). Default slot text becomes the label; attributes map to the items fields: value / disabled / loading / icon / kind / danger / href / target / rel. Nested elements inside an <oas-context-menu-item> become cascading submenus recursively; an <oas-context-menu-group>'s label is the group title (value can act as a radio-group id) and its children flatten to the same level. Adding/removing children or changing their attributes/text re-renders automatically (MutationObserver).
Declarative children (group / divider / nested / danger / href)
Dynamic add/remove (MutationObserver auto refresh)
Checkbox and action items (kind)
kind="checkbox" renders multi-select checkable items (menuitemcheckbox semantics; clicking toggles and writes back the value array); kind="action" is a pure action item (no check state, never writes back value, only emits the event).
Checkbox + action items (kind)
Checked: grid
API
oas-context-menu
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
close-on-scroll | Close the menu on page scroll (default true) | string | true |
items | Menu items JSON | string | [] |
long-press-delay | Long-press duration in ms for touch trigger (default 500) | string | 500 |
open | Controlled open state (writable externally) | boolean | — |
value | Checked set for kind="checkbox" items (JSON array); toggles write back to the host and persist across opens | string | — |
Events
| Event | Description |
|---|---|
oas-open-change | Menu open state changed, detail: { open: boolean } |
oas-select | An item was selected, detail: { value } |
Slots
| Name | Description |
|---|---|
| default | Context menu content (items / groups) |
CSS Variables
| CSS Variable | Default |
|---|---|
--oas-glass-blur | none |
--oas-glass-ring | transparent |
oas-context-menu-item
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
danger | Destructive item: red semantics (delete/exit etc.) | — | — |
disabled | Disable this item | — | — |
href | Link address: with href the item renders as a native <a> (real navigation + still emits oas-select) | — | — |
icon | Leading icon (icon name from the @oas-ui/icons registry) | — | — |
icon-color | Icon color: fixes the icon to this color (overrides the selected/disabled default); defaults to currentColor following the text color (only effective via the items JSON channel; the child-element channel does not parse this attribute) | — | — |
kind | Leaf semantics: radio (default, selectable) / action (no checked state, does not write back value) / checkbox (multi-select, value is the checked-set array) | — | — |
loading | Loading: renders a spinner and blocks clicks; recovers when data-driven | — | — |
rel | Link rel (with href) | — | — |
shortcut | Shortcut hint rendered as a trailing kbd (aligned with the menubar/menu shortcut contract) (only effective via the items JSON channel; the child-element channel does not parse this attribute) | — | — |
target | Link target (with href) | — | — |
value | Selected value (data-carrier field of the declarative child-element channel) | — | — |
Slots
| Name | Description |
|---|---|
| default | Context-menu item label content (default slot text); direct child <oas-context-menu-item> elements recursively become the submenu children |
template[slot="leading"] | Leading media template (or a direct child with slot="leading"): avatars/color chips/any rich leading content, rendered before the label and taking precedence over the icon attribute; replaced by the spinner in the loading state; declarative child channel only (not supported by the items JSON) |
oas-context-menu-group
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
label | Group title (small, secondary color, not clickable) | — | — |
value | Radio-group id (selecting inside the group only updates that group's value) | — | — |
Slots
| Name | Description |
|---|---|
| default | Group items: child <oas-context-menu-item> elements flatten to the same level |
oas-context-menu-divider
Slots
| Name | Description |
|---|---|
| default | Divider data carrier (no attributes; the host parses it as type: "divider") |
Opens at the mouse position; closes on Esc / outside click / selection; role="menu" + menuitem.