<c-menu>
A command menu: a transient panel of actions or navigation choices opened from a trigger (the WAI-ARIA menu-button pattern), authored declaratively with slotted `c-menu-item`, `c-menu-label` and `c-divider` elements. Activating an item fires a one-off `select` event and closes the menu; the menu holds no selected value — that is `c-select`'s job.
Usage
Scrolling
A menu taller than the viewport allows scrolls without a scrollbar: the panel ends on a half-visible item, which is the cue that more items follow, and the wheel, touch and arrow keys scroll as usual. Submenu panels behave the same. To bring the native scrollbar back:
c-menu::part(list),
c-menu-item::part(submenu-list) {
scrollbar-width: auto;
}
<c-menu-item>
A single command in a c-menu.
Put a leading icon in the icon slot (<c-icon slot="icon" path="…">). The
item sizes it to 18px, as its check mark, unless the c-icon sets its own
size; a plain <svg> or <img> is sized the same. For
a set of choices, give each item type="radio" and mark the current one
checked: it shows a check mark and aria-checked. The menu only fires
select; checking the item is yours to do.
Scrolling
A long submenu scrolls like the menu itself: no scrollbar, and a half-visible
item as the cue that more follow. Restore the scrollbar with
c-menu-item::part(submenu-list) { scrollbar-width: auto; }.
Examples
<template>
<div class="example-row">
<c-menu @select="onSelect">
<c-button slot="trigger" appearance="outlined">
Device
<c-icon :path="mdiChevronDown" />
</c-button>
<c-menu-label>Type</c-menu-label>
<c-menu-item value="phone">Phone</c-menu-item>
<c-menu-item value="tablet">Tablet</c-menu-item>
<c-menu-item value="desktop">Desktop</c-menu-item>
<c-divider />
<c-menu-item value="forget" danger>Forget this device</c-menu-item>
</c-menu>
<p>Selected: {{ selected ?? '—' }}</p>
</div>
</template>
<script setup lang="ts">
import { mdiChevronDown } from '@mdi/js';
import { ref } from 'vue';
const selected = ref<null | string>(null);
const onSelect = (event: Event) => {
selected.value = (event as CustomEvent<{ value: string }>).detail.value;
};
</script>
<template>
<div class="example-row">
<c-menu @select="onSelect">
<c-button slot="trigger" appearance="ghost">
Export
<c-icon :path="mdiChevronDown" />
</c-button>
<c-menu-item value="documents">
Documents
<c-menu-item slot="submenu" value="pdf">
<c-icon :path="mdiFilePdfBox" />
PDF
</c-menu-item>
<c-menu-item slot="submenu" value="docx">
<c-icon :path="mdiFileDocument" />
Word document
</c-menu-item>
</c-menu-item>
<c-menu-item value="images">
Images
<c-menu-item slot="submenu" value="png">
<c-icon :path="mdiFilePngBox" />
PNG
</c-menu-item>
<c-menu-item slot="submenu" value="jpg">
<c-icon :path="mdiFileJpgBox" />
JPEG
</c-menu-item>
</c-menu-item>
<c-divider />
<c-menu-item value="settings">Export settings…</c-menu-item>
</c-menu>
<p>Selected: {{ selected ?? '—' }}</p>
</div>
</template>
<script setup lang="ts">
import {
mdiChevronDown,
mdiFileDocument,
mdiFileJpgBox,
mdiFilePdfBox,
mdiFilePngBox,
} from '@mdi/js';
import { ref } from 'vue';
const selected = ref<null | string>(null);
const onSelect = (event: Event) => {
selected.value = (event as CustomEvent<{ value: string }>).detail.value;
};
</script>
<template>
<div class="example-row">
<c-menu @select="onSelect">
<c-button slot="trigger" appearance="text">
<c-icon :path="mdiAccount" />
Account
<c-icon :path="mdiChevronDown" />
</c-button>
<c-menu-item value="profile">View profile</c-menu-item>
<c-menu-item value="billing" disabled>Billing (unavailable)</c-menu-item>
<c-menu-item value="invite">Invite teammate</c-menu-item>
<c-divider />
<c-menu-item value="delete" danger>Delete account</c-menu-item>
</c-menu>
<p>Selected: {{ selected ?? '—' }}</p>
</div>
</template>
<script setup lang="ts">
import { mdiAccount, mdiChevronDown } from '@mdi/js';
import { ref } from 'vue';
const selected = ref<null | string>(null);
const onSelect = (event: Event) => {
selected.value = (event as CustomEvent<{ value: string }>).detail.value;
};
</script>
<template>
<div class="example-row">
<c-menu @select="onTheme">
<c-button slot="trigger" appearance="text">
<c-icon :path="mdiThemeLightDark" />
Theme: {{ theme }}
<c-icon :path="mdiChevronDown" />
</c-button>
<c-menu-label>Theme</c-menu-label>
<c-menu-item
v-for="option in themes"
:key="option.value"
:checked="theme === option.value"
:value="option.value"
type="radio"
>
<c-icon slot="icon" :path="option.icon" />
{{ option.label }}
</c-menu-item>
</c-menu>
</div>
</template>
<script setup lang="ts">
import {
mdiChevronDown,
mdiMonitor,
mdiThemeLightDark,
mdiWeatherNight,
mdiWeatherSunny,
} from '@mdi/js';
import { ref } from 'vue';
const themes = [
{ icon: mdiWeatherNight, label: 'Dark', value: 'dark' },
{ icon: mdiWeatherSunny, label: 'Light', value: 'light' },
{ icon: mdiMonitor, label: 'System', value: 'system' },
];
const theme = ref('dark');
const onTheme = (event: Event) => {
theme.value = (event as CustomEvent<{ value: string }>).detail.value;
};
</script>
<template>
<div class="example-row">
<c-menu @select="onSelect">
<c-button slot="trigger" appearance="ghost">
Export
<c-icon :path="mdiChevronDown" />
</c-button>
<c-menu-item value="documents">
Documents
<c-menu-item slot="submenu" value="pdf">
<c-icon :path="mdiFilePdfBox" />
PDF
</c-menu-item>
<c-menu-item slot="submenu" value="docx">
<c-icon :path="mdiFileDocument" />
Word document
</c-menu-item>
</c-menu-item>
<c-menu-item value="settings">Export settings…</c-menu-item>
</c-menu>
<p>Selected: {{ selected ?? '—' }}</p>
</div>
</template>
<script setup lang="ts">
import { mdiChevronDown, mdiFileDocument, mdiFilePdfBox } from '@mdi/js';
import { ref } from 'vue';
const selected = ref<null | string>(null);
const onSelect = (event: Event) => {
selected.value = (event as CustomEvent<{ value: string }>).detail.value;
};
</script>
<template>
<div class="example-row">
<c-menu @select="onSelect">
<c-button slot="trigger" appearance="outlined">
Settings
<c-icon :path="mdiChevronDown" />
</c-button>
<c-menu-label>Account</c-menu-label>
<c-menu-item value="profile">Profile</c-menu-item>
<c-menu-item value="notifications">Notifications</c-menu-item>
<c-divider />
<c-menu-label>Workspace</c-menu-label>
<c-menu-item value="members">Members</c-menu-item>
<c-menu-item value="billing">Billing</c-menu-item>
</c-menu>
<p>Selected: {{ selected ?? '—' }}</p>
</div>
</template>
<script setup lang="ts">
import { mdiChevronDown } from '@mdi/js';
import { ref } from 'vue';
const selected = ref<null | string>(null);
const onSelect = (event: Event) => {
selected.value = (event as CustomEvent<{ value: string }>).detail.value;
};
</script>
API reference
<c-menu>
A command menu: a transient panel of actions or navigation choices opened from a trigger (the WAI-ARIA menu-button pattern), authored declaratively with slotted `c-menu-item`, `c-menu-label` and `c-divider` elements. Activating an item fires a one-off `select` event and closes the menu; the menu holds no selected value — that is `c-select`'s job.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
distance | distance | number | 0 | Distance from the trigger to the panel, in pixels. Defaults to `0`. |
open | open | boolean | false | Whether the menu is open. Two-way: emits `change:open`. |
position | position | CMenuPosition | 'bottom-start' | Preferred placement of the panel relative to the trigger. |
trigger | trigger | HTMLElement | string | — | Designated trigger: an element elsewhere in the document that opens the menu — its document ID, or the element itself. The same trigger concept as the `trigger` slot, supplied by reference: the menu wires click-to-toggle, arrow-key opening, ARIA and focus return onto it and anchors the panel to it. When both routes are supplied, this prop wins over the slot. |
Events
| Event | Detail | Description |
|---|---|---|
change:open | boolean | Fired whenever the menu opens or closes, carrying the new open state. Named `change:open`, not `update:open`: Vue's runtime silently drops `onUpdate:*` listeners on custom elements (`isModelListener`), so a template `@update:open` would never be attached. |
select | { value: string | undefined } | Fired when a leaf menu item is selected, carrying the item's `value`; bubbles out of the menu so a single listener can handle the whole tree. |
Slots
| Slot | Description |
|---|---|
default | The menu's content: `c-menu-item`, `c-menu-label` and `c-divider` elements |
trigger | The trigger: the element that opens the menu, e.g. a `c-button` |
CSS parts
Style from outside with c-menu::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
trigger | The inline wrapper around the slotted trigger, serving as the panel's anchor |
panel | The floating popover positioned against the trigger |
list | The menu list surface inside the panel |
Types
Importable from the package root: import type { … } from '@cscfi/csc-ui'
CMenuPosition
Preferred placement of the menu panel relative to its trigger: the side, and `-start`/`-end` to align their edges on the cross axis.
export type CMenuPosition =
| 'bottom-end'
| 'bottom-start'
| 'bottom'
| 'left-end'
| 'left-start'
| 'left'
| 'right-end'
| 'right-start'
| 'right'
| 'top-end'
| 'top-start'
| 'top';<c-menu-item>
A single command in a `c-menu`.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
checked | checked | boolean | false | Whether a `radio` item is the checked choice: it shows a check mark and `aria-checked`. The state is yours: the menu fires `select` as usual and never checks an item itself. |
danger | danger | boolean | false | Marks the action as destructive (renders in the error colour). |
disabled | disabled | boolean | false | Disables the item — it is skipped by keyboard nav and emits no select. |
type | type | CMenuItemType | 'command' | What the item is: a `command` (a plain menu item) or one `radio` choice of several, checked with `checked`. |
value | value | string | — | Value reported in the menu's `select` event when this item is chosen. |
Slots
| Slot | Description |
|---|---|
default | The item's content: label text plus optional icons or shortcut hint |
icon | A leading icon, such as a `c-icon`, before the content |
submenu | c-menu-item components for the nested submenu |
CSS parts
Style from outside with c-menu-item::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The item row containing the content and the submenu chevron |
content | The flex wrapper around the default-slot content |
check | The check mark shown while a `radio` item is checked |
submenu-panel | The floating popover holding the submenu |
submenu-list | The submenu list surface inside the popover |
Types
Importable from the package root: import type { … } from '@cscfi/csc-ui'
CMenuItemType
What a menu item is: a plain `command`, or one `radio` choice of several (`role="menuitemradio"`, checked with `checked`).
export type CMenuItemType = 'command' | 'radio';<c-menu-label>
Section label for a group of `c-menu-item`s.
Slots
| Slot | Description |
|---|---|
default | The label text for the menu section |
CSS parts
Style from outside with c-menu-label::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The label element inside the menu list |