A context menu lists the actions for the clicked object in a predictable order, so users find the same action in the same place on every object and surface.
Group order
Groups render in lexicographic order of their ID, with navigation always first. Use these groups, in this order, for new menus and for all Agents window menus:
| Group | Purpose |
|---|---|
navigation |
Open, create, or run the object. The default (double-click or Enter) action comes first. |
1_state |
Change the object's state. |
2_organize |
Change where the object is listed or how it is ordered. |
3_copy |
Copy information about the object to the clipboard. |
4_manage |
Configure or edit the object itself. Destructive actions come last. |
- Order items within a group with
order(orgroup@ninpackage.json) instead of relying on title sorting. - Prefer these groups over inventing new ones. A new group needs a purpose none of them covers.
- Established workbench menus with documented groups (editor, Explorer, terminal, editor title) keep their own group IDs. Add to the closest matching group.
- Group IDs of menus open to extensions are API. When you change one, update every contribution, including
extensions/*/package.json.
Rules
- Destructive actions last. An action that deletes or removes data is the final item of the menu. Never place it mid-menu.
- Same object, same menu. An object shown in several places (list row, tab, header, card) offers the same actions in the same order. Reuse one
MenuIdor the same group IDs rather than building a parallel action list by hand. - Inline actions are in the menu too. Every hover or toolbar action of a row or header also appears in its context menu.
- Only actions for the clicked object. List-wide or unrelated actions belong on the section header, view title, or empty space, not on an item.
- Hide what doesn't apply; disable what can't run now. Use
whenfor actions irrelevant to the object andpreconditionfor applicable actions that are temporarily unavailable, such as single-item actions during multi-selection. - Keep it short. At most about 5 groups and 15 items, with one level of submenus. Use a submenu for 3 or more related targets, and a toggle rather than a submenu for a two-way choice.
- Labels. Use Title Case. End with
...when the action asks for more input or confirmation. Labels must be unique within a menu. - Dynamic actions join their group. When actions must be built in code, merge them into the matching group of the menu's actions instead of appending them after a final separator. Join groups with
Separator.join.
Based on the VS Code context menu UX guidelines, the Windows menu guidelines, and the Apple context menu guidelines.