Menu

Anatomy

Items

• command (default): runs an action and closes the menu.
• checkbox: turns a view option on or off, such as showing a grid. The menu stays open, so people can change several.
• radio: picks one option from its tk-menu-group and closes the menu. Put radios in a titled group.
• Checked items change how people see the screen (sort order, visible columns, density), and the change applies at once. They never hold a form value; that's a Select.
• preventDefault() on an item's click stops both the check change and the close, for example to ask first. Setting checked from code fires nothing.

Danger

• danger marks an action that loses data. It works on command items only.
• Put it last, after a divider.
• Always confirm it with a confirm dialog; end the label with "…" to show that a step follows.
• Red means data loss, not leaving: "Leave team" isn't red. Name the action in the label.

Icons, descriptions, and hints

• Icons: give every item an icon or none. The menu sizes and colors them.
• Descriptions: keep them rare and short; most menus are one line per item.
• Trailing: a shortcut hint or a badge, shown as text. It doesn't set up the shortcut; wire the key yourself. Screen readers read it after the label, so keep it short. Nothing interactive here.

States

Hover and keyboard focus look the same: a light tint on the row. Pointing at an item moves focus to it.

• disabled: the item stays in the menu and can still be reached with the arrow keys, but does nothing. People can see the command exists. If every item is unavailable for the same reason, disable the trigger instead.
• Hide items people will never be allowed to use, such as admin-only actions.
• checked: shows the ✓ on checkbox and radio items.

Opening and closing

Opening moves focus to the first item (the last with ↑).

• The menu opens below the trigger and moves above near the bottom of the screen. It follows the trigger on scroll and is never clipped by its container.
• Long labels are cut with an ellipsis. Menus don't scroll; keep them to about 12 items.

Triggers

• A tk-button with a label and a chevron-down icon for page actions. Don't repeat its word in the items: "Export" opens "PDF" and "CSV", not "Export PDF".
• A more-horizontal tk-icon-button in a type="label" Tooltip for overflow actions, such as on a table row. Name the scope: "Row actions", "More actions".

Context menus

With trigger="context", the trigger slot holds the area people right-click. The menu is otherwise the same. It opens three ways:

• Right-click in the area: the menu opens at the pointer.
• Long press on touch, for 500ms; moving or scrolling cancels it.
• Shift+F10 or the ContextMenu key while focus is in the area. The menu makes the area focusable if it isn't.

Rules for context menus:

• Name the menu with label, or aria-label on the area. The area's text is never used as the name.
• Every command must also be reachable from the main screen. People can't discover a right-click, and touch and keyboard users may never find it.
• Hide items that don't apply here, instead of disabling them.
• No shortcut hints.
• Put the most likely commands first, nearest the pointer.

The browser's own context menu stays available everywhere outside the area.

Submenus

A submenu is a tk-menu inside a menu, with a tk-menu-item as its trigger: the parent row. The row gets its chevron and ARIA, and the submenu takes its name from the row.

• Hover, click, Enter, Space, or → open it. A parent row only opens its submenu; it never runs a command.
• Moving diagonally from the row into the open submenu doesn't close it.
• ← or Esc close the submenu and return focus to its row.
• Choosing an item closes every level and returns focus to the trigger.
• It opens on the side with room. A disabled parent row never opens.
• Radio sets and the ✓ column are per level.

Use submenus sparingly:

• One level only, with at most about 5 items.
• Not to pick a value, and not just to tidy up; use a group title instead.
• If people open the menu to reach the submenu, make the submenu the menu.
• Avoid them on touch-first screens.

When to use

• Use a menu for 3 to about 12 related actions that would take too much space on screen, such as row actions in a table. With fewer, show the buttons. With more, split the menu or rethink the screen.
• Keep the main action of a view visible, never inside a menu.
• Use a Select or Combobox to pick a value that is saved or sent with a form.
• Use a Navigation menu or Sidebar for links. If an item does something, it's a menu item; if it goes somewhere, it's a link.
• Open a menu from a button, on click. Never from a link, never on hover.

Content

• Start labels with a verb, add a noun when the verb alone is unclear. No articles, sentence case.
• End the label with "…" when the action needs more input before it's done.
• Put frequent and important items first, keep related items together, and put danger last.
• Group titles: one or two words, sentence case, no punctuation.

More in Action labels.

Do / Don't

Related

• Select and Combobox: pick a value.
• Navigation menu and Sidebar: links, not actions.
• Icon button and Tooltip: the overflow trigger.
• Dialog: the confirm a danger item opens.
• Split button: a main action with a menu of related ones.

API

tk-menu

CSS: ::part(menu), the panel. No methods; the trigger opens the menu.

tk-menu-item

CSS: ::part(row), the row.

tk-menu-group

Events

No custom events. Listen for click on an item.

Tokens

Values per theme: Color.

Accessibility

Built in:

• The trigger gets aria-haspopup="menu" and aria-expanded. The panel is a menu named by label or the trigger; items are menuitem, menuitemcheckbox, or menuitemradio with their checked and disabled states.
• The menu, its submenus, and its items are one Tab stop. Focus moves in on open and returns as the close table says.
• Disabled items stay reachable and show focus. The ✓ and chevrons are hidden from screen readers.
• A context area gets aria-haspopup, aria-keyshortcuts="Shift+F10", and a tab stop if it had none.
• Every row is at least 32px tall. The panel stays inside the visible viewport when zoomed.

Your part:

• Name a context menu with label, and make every command reachable without it.
• Name the destructive action in a danger item; color alone doesn't tell everyone.
• Keep descriptions short; they're read after the label.

In right-to-left text, → and ← swap.