> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/core-components/dynamic-menu.md).
# Dynamic Menu
`avonni-dynamic-menu`
A button menu whose items are generated from a list of options, with optional search and avatars.
## Overview
**Dynamic Menu** is a Lightning Web Component that renders a button which opens a dropdown of rich, data-driven items—each with optional avatar, metadata, and inline actions—plus optional search, custom content, and a footer.
Use it in your own Lightning Web Components when a menu's items come from data rather than static markup. You supply the items, control the button look and menu alignment, and read selections from the `select` event.
### Use Cases
* **Filter pickers:** Choose a region, status, or category to filter a report.
* **Record switchers:** Let users jump between related records with avatars.
* **Rich action menus:** Offer items with metadata and per-item inline actions.
* **Searchable lists:** Add `allow-search` for long, dynamic option sets.
* **Custom dropdowns:** Use the default and footer slots for headers and buttons.
***
## Use Case Examples
### Example 1: Searchable region filter with actions
**Scenario:** Let users pick a sales region from a data-driven, searchable menu where each region carries metadata and an inline "open dashboard" action.
```html
```
```js
// regionFilter.js
import { LightningElement } from 'lwc';
export default class RegionFilter extends LightningElement {
items = [
{
label: 'North America',
value: 'north-america',
meta: ['142 accounts', 'USD'],
avatar: { fallbackIconName: 'standard:location', initials: 'NA' },
actions: [
{ name: 'open-dashboard', iconName: 'utility:open', alternativeText: 'Open dashboard' }
]
},
{ label: 'Europe', value: 'europe', meta: ['98 accounts', 'EUR'] }
];
selectedValue;
handleSelect(event) {
this.selectedValue = event.detail.value;
}
handleActionClick(event) {
const action = event.detail.name; // 'open-dashboard'
const item = event.detail.item; // the item's value
}
handleClear() {
this.selectedValue = undefined;
}
}
```
**Result:** A brand button that opens a searchable menu of regions with avatars and metadata; selecting fires `select`, the inline icon fires `actionclick`, and the footer button clears the selection.
### Example 2: Simple record switcher
**Scenario:** Provide a compact icon-only menu to switch between recent records.
```html
```
```js
// recordSwitcher.js
import { LightningElement } from 'lwc';
export default class RecordSwitcher extends LightningElement {
records = [
{ label: 'Acme Inc.', value: '001a' },
{ label: 'Global Media', value: '001b' }
];
handleSelect(event) {
const recordId = event.detail.value;
}
}
```
**Result:** An icon button that opens a right-aligned menu; selecting a record fires `select` with its value.
***
## Specifications
### Attributes
| Name | Description | Type | Default | Required |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ | -------------- | -------- |
| `access-key` | The keyboard shortcut for the button menu. | String | — | |
| `allow-search` | If present, display a search box. | Boolean | `false` | |
| `alternative-text` | The assistive text for the button. | String | — | |
| `button-size` | Size of the button. Available options include auto and stretch. | String | `"auto"` | |
| `disabled` | If present, the menu cannot be opened by users. | Boolean | `false` | |
| `group-order` | Reserved for internal use only. Describes the order of this element inside `lightning-button-group`. Valid values include first, middle or last. | String | — | |
| `hide-check-mark` | If present, hide the check mark when selected. | Boolean | `false` | |
| `icon-name` | The name of the icon to be used in the format 'utility:down'. | String | — | |
| `icon-position` | Describes the position of the icon with respect to body. Options include left and right. | String | `"left"` | |
| `icon-size` | The size of the icon. Options include xx-small, x-small, small, medium, or large. | String | `"medium"` | |
| `is-loading` | If present, the menu is in a loading state and shows a spinner. | Boolean | `false` | |
| `items` | Array of item objects. | AvonniDynamicMenuItem\[] | — | |
| `label` | Optional text to be shown on the button. | String | — | |
| `loading-state-alternative-text` | Message displayed while the menu is in the loading state. | String | `"Loading..."` | |
| `menu-alignment` | Determines the alignment of the menu relative to the button. Available options are: auto, left, center, right, bottom-left, bottom-center, bottom-right. The auto option aligns the dropdown menu based on available space. | String | `"left"` | |
| `menu-length` | Maximum length of the menu. Valid values include 5-items, 7-items and 10-items. | String | `"7-items"` | |
| `menu-width` | Minimum width of the menu. Valid values include xx-small, x-small, small, medium and large. | String | `"small"` | |
| `nubbin` | If present, a nubbin is present on the menu. A nubbin is a stub that protrudes from the menu item towards the button menu. The nubbin position is based on the menu-alignment. | Boolean | `false` | |
| `open-menu-on-hover` | Determines whether the menu can be opened by hovering over it. | Boolean | `false` | |
| `search-input-placeholder` | Text that is displayed when the field is empty, to prompt the user for a valid entry. | String | — | |
| `select-on-hover` | Determines whether the menu item can be selected by hovering over it. | Boolean | `false` | |
| `title` | Displays tooltip text when the mouse moves over the button menu. | String | — | |
| `tooltip` | Text to display when the user mouses over or focuses on the button. The tooltip is auto-positioned relative to the button and screen space. | String | — | |
| `value` | Value of the selected item. | String | — | |
| `variant` | The variant changes the look of the button. Accepted variants include bare, bare-inverse, base, border, border-filled, border-inverse brand, brand-outline, container, destructive, destructive-text, inverse, neutral, reset and success. | String | `"border"` | |
### Methods
| Name | Description | Argument Name | Argument Type | Argument Description |
| ------- | -------------------------------------- | ------------- | ------------- | -------------------- |
| `click` | Simulates a mouse click on the button. | | | |
| `close` | Close Dropdown menu. | | | |
| `focus` | Set focus on the button. | | | |
### Slots
| Slot | Description |
| --------- | ---------------------------------------------------------------- |
| `default` | Placeholder for your content. |
| `footer` | Placeholder for actionable components, such as lightning-button. |
### Custom Events
#### `actionclick`
The event fired when a user clicks on an action.
The `actionclick` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | --------------------------- |
| `name` | string | Name of the action clicked. |
| `item` | string | The value of the item. |
The event properties are as follows.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `close`
The event fired when you close the dropdown menu.
The `close` event doesn't return any parameters.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `open`
The event fired when you open the dropdown menu.
The `open` event doesn't return any parameters.
| Property | Value | Description |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
#### `select`
Select event.
The `select` event returns the following parameters.
| Parameter | Type | Description |
| --------- | ------ | ------------------------------- |
| `value` | string | The value of the selected item. |
The event properties are as follows.
| Property | Value | Description |
| ---------- | ----- | ---------------------------------------------------------------------------------- |
| bubbles | false | This event does not bubble. |
| cancelable | true | This event can be canceled. You can call `preventDefault()` on this event. |
| composed | false | This event does not propagate outside of the component in which it was dispatched. |
### Styling Hooks
| CSS Variable | Type | Default |
| ---------------------------------------------------------------- | --------- | --------------------------- |
| `--avonni-dynamic-menu-line-height` | dimension | `1.875rem` |
| `--avonni-dynamic-menu-radius-border` | radius | `0.25rem` |
| `--avonni-dynamic-menu-sizing-border` | sizing | `1px` |
| `--avonni-dynamic-menu-styling-border` | styling | `solid` |
| `--avonni-dynamic-menu-label-font-family` | font | — |
| `--avonni-dynamic-menu-label-font-size` | font | `0.8175rem` |
| `--avonni-dynamic-menu-label-font-style` | font | `normal` |
| `--avonni-dynamic-menu-label-font-weight` | font | `400` |
| `--avonni-dynamic-menu-bare-color-background` | color | `transparent` |
| `--avonni-dynamic-menu-bare-color-background-active` | color | `transparent` |
| `--avonni-dynamic-menu-bare-color-background-hover` | color | `transparent` |
| `--avonni-dynamic-menu-bare-color-border` | color | `transparent` |
| `--avonni-dynamic-menu-bare-color-border-active` | color | `#014486` |
| `--avonni-dynamic-menu-bare-color-border-hover` | color | `transparent` |
| `--avonni-dynamic-menu-bare-text-color` | color | `#747474` |
| `--avonni-dynamic-menu-bare-text-color-active` | color | `#014486` |
| `--avonni-dynamic-menu-bare-text-color-hover` | color | `#014486` |
| `--avonni-dynamic-menu-bare-inverse-color-background` | color | `transparent` |
| `--avonni-dynamic-menu-bare-inverse-color-background-active` | color | `transparent` |
| `--avonni-dynamic-menu-bare-inverse-color-background-hover` | color | `transparent` |
| `--avonni-dynamic-menu-bare-inverse-color-border` | color | `transparent` |
| `--avonni-dynamic-menu-bare-inverse-color-border-active` | color | `rgba(255, 255, 255, 0.75)` |
| `--avonni-dynamic-menu-bare-inverse-color-border-hover` | color | `transparent` |
| `--avonni-dynamic-menu-base-color-background` | color | `transparent` |
| `--avonni-dynamic-menu-base-color-background-active` | color | `transparent` |
| `--avonni-dynamic-menu-base-color-background-hover` | color | `transparent` |
| `--avonni-dynamic-menu-base-color-border` | color | `transparent` |
| `--avonni-dynamic-menu-base-color-border-active` | color | `#014486` |
| `--avonni-dynamic-menu-base-color-border-hover` | color | `#014486` |
| `--avonni-dynamic-menu-base-text-color` | color | `#0176d3` |
| `--avonni-dynamic-menu-base-text-color-active` | color | `#014486` |
| `--avonni-dynamic-menu-base-text-color-hover` | color | `#014486` |
| `--avonni-dynamic-menu-border-color-background` | color | `transparent` |
| `--avonni-dynamic-menu-border-color-background-active` | color | `transparent` |
| `--avonni-dynamic-menu-border-color-background-hover` | color | `transparent` |
| `--avonni-dynamic-menu-border-color-border` | color | `#747474` |
| `--avonni-dynamic-menu-border-color-border-active` | color | `#014486` |
| `--avonni-dynamic-menu-border-color-border-hover` | color | `#747474` |
| `--avonni-dynamic-menu-border-text-color` | color | `#747474` |
| `--avonni-dynamic-menu-border-text-color-active` | color | `#014486` |
| `--avonni-dynamic-menu-border-text-color-hover` | color | `#014486` |
| `--avonni-dynamic-menu-border-filled-color-background` | color | `#fff` |
| `--avonni-dynamic-menu-border-filled-color-background-active` | color | `#fff` |
| `--avonni-dynamic-menu-border-filled-color-background-hover` | color | `#fff` |
| `--avonni-dynamic-menu-border-filled-color-border` | color | `#747474` |
| `--avonni-dynamic-menu-border-filled-color-border-active` | color | `#014486` |
| `--avonni-dynamic-menu-border-filled-color-border-hover` | color | `#747474` |
| `--avonni-dynamic-menu-border-filled-text-color` | color | `#747474` |
| `--avonni-dynamic-menu-border-filled-text-color-active` | color | `#014486` |
| `--avonni-dynamic-menu-border-filled-text-color-hover` | color | `#014486` |
| `--avonni-dynamic-menu-border-inverse-color-background` | color | `transparent` |
| `--avonni-dynamic-menu-border-inverse-color-background-active` | color | `transparent` |
| `--avonni-dynamic-menu-border-inverse-color-background-hover` | color | `transparent` |
| `--avonni-dynamic-menu-border-inverse-color-border` | color | `#c9c9c9` |
| `--avonni-dynamic-menu-border-inverse-color-border-active` | color | `hsla(0, 0%, 100%, 0.5)` |
| `--avonni-dynamic-menu-border-inverse-color-border-hover` | color | `#c9c9c9` |
| `--avonni-dynamic-menu-border-inverse-text-color` | color | `#fff` |
| `--avonni-dynamic-menu-border-inverse-text-color-active` | color | `hsla(0, 0%, 100%, 0.5)` |
| `--avonni-dynamic-menu-border-inverse-text-color-hover` | color | `hsla(0, 0%, 100%, 0.5)` |
| `--avonni-dynamic-menu-brand-color-background` | color | `#0176d3` |
| `--avonni-dynamic-menu-brand-color-background-active` | color | `#014486` |
| `--avonni-dynamic-menu-brand-color-background-hover` | color | `#014486` |
| `--avonni-dynamic-menu-brand-color-border` | color | `#0176d3` |
| `--avonni-dynamic-menu-brand-color-border-active` | color | `#014486` |
| `--avonni-dynamic-menu-brand-color-border-hover` | color | `#014486` |
| `--avonni-dynamic-menu-brand-text-color` | color | `#fff` |
| `--avonni-dynamic-menu-brand-text-color-active` | color | `#fff` |
| `--avonni-dynamic-menu-brand-text-color-hover` | color | `#fff` |
| `--avonni-dynamic-menu-outline-brand-color-background` | color | `#fff` |
| `--avonni-dynamic-menu-outline-brand-color-background-active` | color | `#f3f3f3` |
| `--avonni-dynamic-menu-outline-brand-color-background-hover` | color | `#f3f3f3` |
| `--avonni-dynamic-menu-outline-brand-color-border` | color | `#0176d3` |
| `--avonni-dynamic-menu-outline-brand-color-border-active` | color | `#0176d3` |
| `--avonni-dynamic-menu-outline-brand-color-border-hover` | color | `#0176d3` |
| `--avonni-dynamic-menu-container-color-background` | color | `transparent` |
| `--avonni-dynamic-menu-container-color-background-active` | color | `transparent` |
| `--avonni-dynamic-menu-container-color-background-hover` | color | `transparent` |
| `--avonni-dynamic-menu-container-color-border` | color | `transparent` |
| `--avonni-dynamic-menu-container-color-border-active` | color | `#014486` |
| `--avonni-dynamic-menu-container-color-border-hover` | color | `transparent` |
| `--avonni-dynamic-menu-container-text-color` | color | `#747474` |
| `--avonni-dynamic-menu-container-text-color-active` | color | `#014486` |
| `--avonni-dynamic-menu-container-text-color-hover` | color | `#014486` |
| `--avonni-dynamic-menu-destructive-color-background` | color | `#ba0517` |
| `--avonni-dynamic-menu-destructive-color-background-active` | color | `#8e030f` |
| `--avonni-dynamic-menu-destructive-color-background-hover` | color | `#8e030f` |
| `--avonni-dynamic-menu-destructive-color-border` | color | `#ba0517` |
| `--avonni-dynamic-menu-destructive-color-border-active` | color | `#8e030f` |
| `--avonni-dynamic-menu-destructive-color-border-hover` | color | `#ba0517` |
| `--avonni-dynamic-menu-destructive-text-color` | color | `#fff` |
| `--avonni-dynamic-menu-destructive-text-color-active` | color | `#fff /**` |
| `--avonni-dynamic-menu-text-destructive-color-background` | color | `#fff` |
| `--avonni-dynamic-menu-text-destructive-color-background-active` | color | `#f3f3f3` |
| `--avonni-dynamic-menu-text-destructive-color-background-hover` | color | `#f3f3f3` |
| `--avonni-dynamic-menu-text-destructive-color-border` | color | `#747474` |
| `--avonni-dynamic-menu-text-destructive-color-border-active` | color | `#747474` |
| `--avonni-dynamic-menu-text-destructive-color-border-hover` | color | `#747474` |
| `--avonni-dynamic-menu-text-destructive-text-color` | color | `#8e030f` |
| `--avonni-dynamic-menu-text-destructive-text-color-active` | color | `#8e030f` |
| `--avonni-dynamic-menu-text-destructive-text-color-hover` | color | `#8e030f` |
| `--avonni-dynamic-menu-inverse-color-background` | color | `transparent` |
| `--avonni-dynamic-menu-inverse-color-background-active` | color | `#f3f3f3` |
| `--avonni-dynamic-menu-inverse-color-background-hover` | color | `#f3f3f3` |
| `--avonni-dynamic-menu-inverse-color-border` | color | `#747474` |
| `--avonni-dynamic-menu-inverse-color-border-active` | color | `#747474` |
| `--avonni-dynamic-menu-inverse-color-border-hover` | color | `#747474` |
| `--avonni-dynamic-menu-inverse-text-color` | color | `#fff` |
| `--avonni-dynamic-menu-inverse-text-color-active` | color | `#014486` |
| `--avonni-dynamic-menu-inverse-text-color-hover` | color | `#014486` |
| `--avonni-dynamic-menu-neutral-color-background` | color | `#fff` |
| `--avonni-dynamic-menu-neutral-color-background-active` | color | `#f3f3f3` |
| `--avonni-dynamic-menu-neutral-color-background-hover` | color | `#f3f3f3` |
| `--avonni-dynamic-menu-neutral-color-border` | color | `#747474` |
| `--avonni-dynamic-menu-neutral-color-border-active` | color | `#747474` |
| `--avonni-dynamic-menu-neutral-color-border-hover` | color | `#747474` |
| `--avonni-dynamic-menu-neutral-text-color` | color | `#0176d3` |
| `--avonni-dynamic-menu-neutral-text-color-active` | color | `#014486` |
| `--avonni-dynamic-menu-neutral-text-color-hover` | color | `#014486` |
| `--avonni-dynamic-menu-success-color-background` | color | `#45c65a` |
| `--avonni-dynamic-menu-success-color-background-active` | color | `#2e844a` |
| `--avonni-dynamic-menu-success-color-background-hover` | color | `#2e844a` |
| `--avonni-dynamic-menu-success-color-border` | color | `#91db8b` |
| `--avonni-dynamic-menu-success-color-border-active` | color | `#2e844a` |
| `--avonni-dynamic-menu-success-color-border-hover` | color | `#2e844a` |
| `--avonni-dynamic-menu-success-text-color` | color | `#181818` |
| `--avonni-dynamic-menu-success-text-color-active` | color | `#fff` |
| `--avonni-dynamic-menu-success-text-color-hover` | color | `#fff` |
| `--avonni-dynamic-menu-reset-color-background` | color | `transparent` |
| `--avonni-dynamic-menu-reset-color-background-active` | color | `transparent` |
| `--avonni-dynamic-menu-reset-color-background-hover` | color | `transparent` |
| `--avonni-dynamic-menu-reset-color-border` | color | `transparent` |
| `--avonni-dynamic-menu-reset-color-border-active` | color | `transparent` |
| `--avonni-dynamic-menu-reset-color-border-hover` | color | `transparent` |
| `--avonni-dynamic-menu-reset-text-color` | color | `#080707` |
| `--avonni-dynamic-menu-reset-text-color-active` | color | `#080707` |
| `--avonni-dynamic-menu-reset-text-color-hover` | color | `#080707` |
| `--avonni-dynamic-menu-dropdown-color-background` | color | `white` |
| `--avonni-dynamic-menu-item-color-background` | color | `#ffffff` |
| `--avonni-dynamic-menu-item-color-background-hover` | color | `#f3f2f2` |
| `--avonni-dynamic-menu-item-check-mark-color` | color | `#0176d3` |
| `--avonni-dynamic-menu-item-text-color` | color | `#080707` |
| `--avonni-dynamic-menu-item-font-size` | font | `0.75rem` |
| `--avonni-dynamic-menu-item-font-style` | font | `normal` |
| `--avonni-dynamic-menu-item-font-weight` | font | `400` |
| `--avonni-dynamic-menu-bare-inverse-background-color` | color | — |
| `--avonni-dynamic-menu-bare-inverse-background-color-active` | color | — |
| `--avonni-dynamic-menu-bare-inverse-background-color-hover` | color | — |
| `--avonni-dynamic-menu-text-color` | color | — |
| `--avonni-dynamic-menu-text-color-active` | color | — |
| `--avonni-dynamic-menu-text-color-hover` | color | — |
## Key Considerations
* **Data-driven items:** Items come from the `items` array, not static markup—each needs a unique `value`.
* **Inline actions:** Per-item `actions` fire `actionclick` with the action `name` and the item's value, separate from `select`.
* **Cancelable select:** The `select` event is cancelable—call `preventDefault()` to veto a selection.
* **Slots:** Use the default slot for a header and the `footer` slot for actions like a clear/reset button.
* **Sizing:** `menu-width` sets minimum width; `menu-length` caps visible items before scrolling.
* **Best Practice:** Give each item a unique `value` and set `alternative-text` (or a `label`) on the button so the trigger is accessible.
***
## Troubleshooting Common Issues
* **Menu is empty:** Verify `items` is a non-empty array with `label` and unique `value` on each entry.
* **Selection not captured:** Confirm `onselect` is wired and read `event.detail.value`.
* **Action and select firing together:** Inline actions emit `actionclick`; handle them separately from `select` to avoid double handling.
* **If issues persist:** Contact our support team at for assistance.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.avonnicomponents.com/lwc-components/core-components/dynamic-menu.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.