To pick a value in a form, take CdsSelect — it stays visible and gets submitted. For a short hint on hover use CdsTooltip, and for a dialog that demands an answer use CdsModal. The content of a menu is usually built from CdsList.
Inside the menu works CdsOverlay: it computes the coordinates, flips the panel when there is not enough room up to the edge of the screen, and recalculates the position on scroll. That is why the menu shares its positioning and opening props with the overlay.
Variations
Activators
A menu is opened by an activator element — you can set it in three ways:
- Through the
activatorslot — the props from the slot (v-bind="props") attach the handlers and the aria attributes to the element. This is the default way: the activator sits next to the menu. - Through the parent —
activator="parent"takes the element that contains theCdsMenu. Handy when the activator is already built and you do not want to wrap it. - Through a selector —
activator="#id"links the menu to any element on the page, even a distant one in the markup.
Opening
By default the menu opens on click. The open-on-hover prop switches it to hover — this is how navigation menus behave; a click then does not open the panel. The open-delay and close-delay delays (300 and 250 ms) keep the menu from flickering when the cursor just passes by. Together with open-on-hover, opening on focus is enabled as well — turn it off with :open-on-focus="false" if the menu should react to the mouse only.
Position
The location prop sets the side of the activator the menu appears on: bottom by default, top, end, bottom end — the side and the alignment. If there is not enough room, the menu flips to the opposite edge on its own. The offset prop tunes the distance to the activator, and viewport-margin sets the minimum gap to the edge of the screen.
Sizes
The width of the menu equals the width of its content. The min-width, max-width and max-height props set the bounds: the minimum width keeps the panel from collapsing on short items, and a limited height turns on scrolling instead of a full-screen menu.
Closing
The menu closes on a click inside the content, on a click outside and on Esc. The :close-on-content-click="false" prop keeps the panel open — you need that when it holds checkboxes, fields or several steps in a row. The persistent prop ignores the outside click and Esc: then the menu can only be closed by your own button through v-model.
Nested menus
Menus can be nested into each other: every list item becomes an activator (activator="parent") for a child CdsMenu with the submenu prop — it shifts the panel sideways and moves the navigation to the left and right arrow keys. The open-on-hover prop opens the submenu on hover, and :open-on-focus="false" keeps it from opening while tabbing through.
Animation
The transition prop changes the animation the panel appears with.
Slots
| Slot | Description |
|---|---|
activator | The element that opens the menu. The slot props (props) attach the handlers to it |
default | The content of the panel. Usually CdsList, CdsCard or CdsSurface |
Guidelines
Scenarios
Actions on a record
Rare actions on a table row or a card are collected in a menu behind the "⋮" button: the row stays clean, and the actions do not compete with the main button. location="bottom end" pins the panel to the right edge of the activator, slim on the list removes the extra paddings, and aria-label names the record the menu belongs to.
Context menu
A menu can open at the point of the click: the contextmenu handler puts the cursor coordinates into target, and v-model controls the visibility — no activator is needed here. A new click moves the open panel to the new spot. The default animation is meant for an element activator, so for a menu placed by coordinates set a CSS animation — for example, transition="scale-transition".
Menu in the header
In the application header a menu solves two tasks: it expands the navigation sections and collects everything about the account behind the avatar. The activator of the user menu is a CdsAvatar inside a button with an aria-label, location="bottom end" pins the panel to the right edge, and min-width keeps it from jumping in width. The first list item shows whose account it is, and CdsListItemDivider separates the sections from signing out.
Filter with several values
When several values are picked inside a menu, the panel must not close on the very first click: :close-on-content-click="false" keeps it open, and v-model lets the "Apply" button close the menu. The selection piles up in a draft and is applied as a whole — until the button is pressed, the list of records does not change.
API
Props
| Name | Type | Default | Description |
|---|---|---|---|
activator | (string & {}) | Element | "parent" | ComponentPublicInstance | undefined | — | The element that activates the component |
activatorProps | Record<string, any> | undefined | {} | Props for the activator element |
attach | string | boolean | Element | undefined | — | Sets the DOM element the overlay content is moved to. It accepts a direct element reference, a querySelector string, or true to disable moving. By default the body element is used. Changing this prop is usually not recommended except for edge cases: the default positioning algorithm handles most scenarios better than it can without moving, and unexpected behavior may appear if the menu ends up being a child of its activator. |
captureFocus | boolean | undefined | true | Returns the focus back into the content if it has left it — for example on Tab from the end of the page. A mouse click does not steal the focus. |
closeDelay | string | number | undefined | 250 | Delay in milliseconds before the component closes. Works only together with open-on-hover. |
closeOnBack | boolean | undefined | true | Closes the overlay content when the browser Back button is pressed or $router.back() is called, cancelling the original navigation. persistent overlays cancel the navigation and animate as if they were clicked outside instead of closing. |
closeOnContentClick | boolean | undefined | true | Hide the component on a click on the content |
contained | boolean | undefined | — | Limits the size of the component and of its grid to the offset parent. Implies the absolute and attach props. (Note: the parent element must have position: relative.) |
contentClass | any | — | Applies a custom class to the content element. This is handy because the content is moved to the beginning of the cds-app component (unless attach is set) and cannot be selected with classes passed to the component directly. |
contentProps | any | — | Applies custom props to the moved content |
disabled | boolean | null | undefined | null | Disabled state |
eager | boolean | undefined | — | Renders the content of the component right away. Useful when you have content that is not in the DOM but has to be indexed for SEO. |
height | string | number | undefined | — | Component height |
id | string | undefined | — | Unique identifier that links the menu to its activator. If it is not set, it is generated automatically. |
location | Anchor | undefined | 'bottom' | Sets the anchor point used to position the component, aligning it horizontally, vertically or in both directions |
locationStrategy | "static" | "connected" | LocationStrategyFunction | undefined | 'connected' | Sets the way the overlay content is positioned. By default static is used, which centers the content in its container. Use connected to attach the content to the activator element. |
maxHeight | string | number | undefined | — | Maximum component height |
maxWidth | string | number | undefined | — | Maximum component width |
minHeight | string | number | undefined | — | Minimum component height |
minWidth | string | number | undefined | — | Minimum component width |
modelValue | boolean | undefined | — | The v-model value of the component. If the component supports the multiple prop, an empty array is used by default. |
noClickAnimation | boolean | undefined | — | Disables the bounce effect on a click outside the content element when persistent is set. |
offset | string | number | number[] | undefined | 4 | Increases the distance to the target. If two numbers are passed, the second one shifts the anchor sideways, away from the target. |
opacity | string | number | undefined | — | Opacity of the scrim element. Applies only when scrim=true. |
openDelay | string | number | undefined | 300 | Delay in milliseconds before the component opens. Works only together with open-on-hover. |
openOnClick | boolean | undefined | — | Show the component on a click on the activator |
openOnFocus | boolean | undefined | — | Show the component when the activator gets focus |
openOnHover | boolean | undefined | — | Show the component on hover over the activator |
origin | Anchor | "auto" | "overlap" | undefined | 'auto' | Sets the anchor point of the overlay content that is aligned with the location anchor of the target. With "auto" the opposite side of the location point is used. With "overlap" the same anchor point is used, so the overlay overlaps the target. It also sets the CSS transform-origin property for the enter/leave transitions. |
persistent | boolean | undefined | — | A click outside the element or the Esc key does not close it. |
retainFocus | boolean | undefined | — | Traps Tab navigation inside the content: from the last focusable element the focus moves to the first one and back. |
scrim | string | boolean | undefined | false | Backdrop shown while the overlay is active. Accepts true/false to toggle the backdrop and a string to set its color. |
scrollStrategy | "none" | "close" | "block" | "reposition" | ScrollStrategyFunction | undefined | 'none' | Strategy applied when the component is active and the user scrolls the page. |
stickToTarget | boolean | undefined | — | Lets the overlay content go off screen while scrolling. |
submenu | boolean | undefined | — | Opens and closes the menu with the left/right arrow keys instead of up/down (for nested menus). |
target | (string & {}) | Element | "parent" | ComponentPublicInstance | "cursor" | [x: number, y: number] | undefined | — | When locationStrategy is set to "connected", specify the element or the array of x, y coordinates the overlay is positioned against. By default the activator element is used. |
theme | string | undefined | — | Component theme |
transition | string | boolean | (TransitionProps & { component?: Component | undefined; }) | { component: Component; } | null | undefined | { component: CdsModalTransition } | Transition animation |
viewportMargin | string | number | undefined | 12 | Sets a custom viewport margin for the overlay content |
width | string | number | undefined | — | Component width |
zIndex | string | number | undefined | 2000 | The z-index value of the component. |
Events
| Name | Type | Description |
|---|---|---|
afterEnter | [] | Fired after the opening animation of the menu has finished |
afterLeave | [] | Fired after the closing animation of the menu has finished |
update:modelValue | [value: boolean] | Fired when the menu is opened or closed. Passes the new visibility state |
Slots
| Name | Type | Description |
|---|---|---|
activator | { isActive: boolean; props: Record<string, any>; targetRef: TemplateRef; } | Slot for the element that acts as the activator of the overlay. |
default | { isActive: Ref<boolean, boolean>; } | Slot for the overlay content. |
Exposed
| Name | Type | Description |
|---|---|---|
activatorEl | HTMLElement | undefined | The DOM element of the activator. |
activatorRef | TemplateRef | Template ref for assigning the activator manually. |
animateClick | () => void | Runs the bounce animation of the content — the same as on a click outside a persistent overlay. |
contentEl | HTMLElement | undefined | The DOM element of the overlay content. |
globalTop | boolean | Whether the overlay is the top one in the global stack of open overlays. |
rootEl | HTMLElement | undefined | The root DOM element of the overlay. |
scrimEl | HTMLElement | undefined | The DOM element of the scrim that dims the page. |
targetEl | HTMLElement | undefined | The DOM element of the positioning target. |
targetRef | TemplateRef | Template ref for assigning the positioning target manually. |
updateLocation | ((e: Event) => void) | undefined | Recalculates the position of the content relative to the target. |