-
-
Notifications
You must be signed in to change notification settings - Fork 260
Expand file tree
/
Copy pathContextMenu.svx
More file actions
100 lines (58 loc) · 7.87 KB
/
Copy pathContextMenu.svx
File metadata and controls
100 lines (58 loc) · 7.87 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
---
components: ["ContextMenu", "ContextMenuGroup", "ContextMenuRadioGroup", "ContextMenuOption", "ContextMenuDivider"]
description: Context menus display contextual actions on right-click, with nested submenus and checkbox or radio selection patterns.
---
<script>
</script>
## Basic
In the examples, right click anywhere within the iframe. The context menu appears when right-clicking anywhere in the window. Use ContextMenuOption for menu items and ContextMenuDivider for visual separation.
The root element has `role="menu"`. Set `labelText` or `aria-label` on ContextMenu so assistive technologies get a meaningful name. This matters most for the default window-wide behavior (target unset), where there is no visible trigger to label the menu with `aria-labelledby`.
<FileSource src="/framed/ContextMenu/ContextMenu" />
## Context menu options
`ContextMenuOption` supports the following props:
| Prop | Description |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `labelText` | Primary label (or use the `labelChildren` slot; see the API reference). |
| `shortcutText` | Keyboard hint shown on the right; can be used with or without an icon. For example, pass **⌘C** as the hint text, or show individual keys in prose as <DocKbd label="⌘" />+<DocKbd label="C" />. |
| `icon` | Carbon icon component to the left of the label. When an icon is set, the option is indented automatically so rows align; you do not need to pass `indented` for icon rows. |
| `indented` | Indent the label without an icon, for example to align with submenu parents or nested items (see [Nested menu](#nested-menu), [Custom target](#custom-target), and [Multiple targets](#multiple-targets)). |
| `disabled` | Non-interactive, dimmed row. |
| `kind` | `"default"` or `"danger"` for destructive actions. |
For options inside `ContextMenuGroup`, see [Selectable](#selectable), [Selectable (nested)](#selectable-nested), and [Radio group](#radio-group).
<FileSource src="/framed/ContextMenu/ContextMenuOptionProps" />
## Nested menu
Put children inside a parent `ContextMenuOption` to open a flyout submenu. Use `indented` on the parent when it has no icon so the label aligns with other rows.
Submenus can contain:
| Kind | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Plain options | Nested `ContextMenuOption` rows for ordinary actions (no selection state). This page’s example below mixes plain rows with a selectable group; see **Open with** → Preview / Editor. |
| Selectable group | A nested `ContextMenuGroup` with an accessible label; options act as checkboxes and share `bind:selectedIds`. See [Selectable (nested)](#selectable-nested); the **Export as** branch in this example shows the same pattern alongside plain items. |
| Radio group | A nested `ContextMenuRadioGroup` with `bind:selectedId` so only one choice is active. See [Radio group (nested)](#radio-group-nested). |
Toggling a checkbox or radio item in a nested submenu leaves that flyout open so you can change several choices; the root menu still closes when you pick a plain action row or click outside.
<FileSource src="/framed/ContextMenu/ContextMenuNested" />
## Targets
Control which element triggers the menu.
### Custom target
By default, the context menu triggers when you right-click anywhere in the window.
Set `target` to specify which element triggers the context menu.
<FileSource src="/framed/ContextMenu/ContextMenuTarget" />
### Multiple targets
Set `target` to an array of elements to trigger the context menu from multiple sources.
<FileSource src="/framed/ContextMenu/ContextMenuTargets" />
## Selection
Let options act as checkboxes or radios, standalone or grouped.
### Selectable
Use selectable for a single toggle item, or wrap options in ContextMenuGroup with `bind:selectedIds` for a checkbox-style group. Provide an id on each option in the group. The standalone toggle and the group items are independent, and the group tracks every chosen option in selectedIds.
<FileSource src="/framed/ContextMenu/ContextMenuSelectable" />
### Selectable (nested)
Put ContextMenuGroup inside a parent ContextMenuOption to show the checkbox-style group in a flyout submenu. Use `bind:selectedIds` for the chosen values. See also [Nested menu](#nested-menu) for a full submenu example that includes both plain options and grouped selection.
<FileSource src="/framed/ContextMenu/ContextMenuSelectableNested" />
### Radio group
Use ContextMenuRadioGroup to organize related options as a radio set: only one option can be selected at a time, and `bind:selectedId` reflects the active choice.
<FileSource src="/framed/ContextMenu/ContextMenuGroups" />
### Radio group (nested)
Put ContextMenuRadioGroup inside a parent ContextMenuOption to show the radio set in a flyout submenu, similar to the nested checkbox group in [Nested menu](#nested-menu). Use `bind:selectedId` for the active choice.
<FileSource src="/framed/ContextMenu/ContextMenuRadioGroupNested" />
## Prevent menu from closing
Use `preventDefault()` on individual context menu option click events to prevent the menu from closing when that option is clicked. Use this to keep the menu open after performing an action.
<FileSource src="/framed/ContextMenu/ContextMenuPreventDefault" />