ki-menu
@kimen/elements/ki-menu- Source
- Agent reference
Pair ki-menu with a named button in the same document or shadow root. The
button ID goes in anchor. Use type="button" when the trigger is in a form.
<ki-button id="row-actions" type="button">Actions</ki-button><ki-menu anchor="row-actions" filter-label="Filter actions"><ki-menu-group label="Edit"> <ki-menu-item value="rename" shortcut="F2">Rename</ki-menu-item> <ki-menu-item value="move" disabled>Move to…</ki-menu-item> <ki-menu-item value="pin" type="checkbox" checked>Pin to sidebar</ki-menu-item></ki-menu-group><ki-divider></ki-divider><ki-menu-item value="delete" tone="danger">Delete</ki-menu-item></ki-menu>Enter, Space and Down open at the first item. Up opens at the last. A filterable menu starts in the filter, and Down enters the results. Use Up, Down, Home, End, and type-ahead to move between actions. Disabled actions can receive focus. Escape returns to the trigger. Tab continues from the trigger in the page’s tab order.
Listen for ki-select on the menu to receive { value, checked? }. Checkboxes
keep the menu open. Plain and radio actions dismiss it. The radio group is
scoped to its ki-menu-group, with ungrouped radios forming their own set.
Use the header slot for informational content and the start slot of an
item for an icon or avatar. A shortcut displays the application’s shortcut
hint.
API reference
When to use: row actions, account commands, split buttons, and overflow actions.
When not to use: form values, navigation destinations, or long action lists.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
anchor | anchor | string | '' | Literal ID of the menu button in the same document or containing shadow root. |
filter-label | filterLabel | string | '' | Accessible name and placeholder of the filter. Omit to hide the field. |
filter-results-label | filterResultsLabel | string | 'Matching actions: {count}' | Polite results message. The menu substitutes the number of matches for {count}. |
open | open | boolean | false | Whether the popup is open. Reflected when the user opens or dismisses it. |
placement | placement | "bottom-end" | "bottom-start" | "top-end" | "top-start" | 'bottom-start' | Preferred side and logical alignment. Flips when the opposite side has more room. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-select | CustomEvent<KiMenuSelectDetail> | Reports the selected action and, for a checkbox or radio, its new checked state. |
Slots
| Slot | Description |
|---|---|
| (default) | Place ki-menu-item, ki-menu-group, and ki-divider here. |
header | Informational content above the actions, such as account details. |
CSS parts
| Part | Description |
|---|---|
filter | The filter field. |
header | The informational header. |
menu | The named menu containing the actions. |
popup | The anchored surface. |
CSS custom properties
The public styling contract of ki-menu: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-density-control-offset | Added to the block size of every scaled control and row (button, icon button, field, select, textarea, option, list item, tab). Components floor the result at ki.size.target-min. |
--ki-density-target-min | The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). |
--ki-menu-backdrop-filter | Complete backdrop filter applied to the popup. |
--ki-menu-bg | Base fill of the popup surface. |
--ki-menu-bg-image | Optional image composited over the popup fill. |
--ki-menu-border | Popup edge and the filter divider. |
--ki-menu-border-width | Thickness of menu border and dividers. |
--ki-menu-fg | Text over the popup surface. |
--ki-menu-filter-icon-size | Size of the search icon. |
--ki-menu-focus-color | Color of a visible keyboard focus outline. |
--ki-menu-focus-width | Width of a visible keyboard focus outline. |
--ki-menu-font-family | Family for action labels and the filter. |
--ki-menu-font-size | Text size for action labels and the filter. |
--ki-menu-gap | Inline space between the parts of a row. |
--ki-menu-inline-padding | Start and end inset of an action, group label, or filter. |
--ki-menu-item-height | Default action row minimum height. |
--ki-menu-item-radius | Action row corner radius. |
--ki-menu-line-height | Line height for action labels and the filter. |
--ki-menu-max-block-size | Maximum popup height, bounded by the viewport. |
--ki-menu-max-inline-size | Maximum popup width, bounded by the viewport. |
--ki-menu-meta-fg | Foreground for shortcut hints and the filter placeholder. |
--ki-menu-min-inline-size | Default minimum popup width, bounded by the viewport. |
--ki-menu-padding | Space inside the popup. |
--ki-menu-radius | Popup corner radius. |
--ki-menu-shadow | Popup elevation shadow. |
--ki-menu-touch-target | Minimum action and filter height for coarse pointers. |