Codex Direction:
Menu #
Dropdown menu of items.
Designed for use in components, like Select and Lookup, that display a menu below another element (for example, a text input). This component renders a list of items, manages which item is selected, highlighted, and active, and handles keyboard navigation. It does not display the selected item or manage an input; the parent component needs to do that.
The selected and expanded props must be bound with v-model, even if the parent component doesn't use them. Without these v-model bindings, the menu won't function correctly.
The menu itself is not focusable; for keyboard navigation to work, the parent component needs to provide a focusable element, listen for keydown events on that element, and pass those events to the menu by calling the delegateKeyNavigation method.
WARNING
This is not a standalone component. It's intended for use inside other components, mainly within Codex. For example, the Select and Lookup components use this component internally.
Demos #
Simple menu with input #
- One
- Two
- Three
- Four
vue
<template>
<div class="cdx-docs-input-with-menu">
<cdx-text-input
v-model="selectedValue"
class="cdx-docs-input-with-menu__input"
:aria-expanded="expanded"
@click="onClick"
@blur="expanded = false"
@keydown="onKeydown"
/>
<cdx-menu
ref="menu"
v-model:selected="selectedValue"
v-model:expanded="expanded"
:menu-items="menuItems"
/>
</div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import { CdxMenu, CdxTextInput } from '@wikimedia/codex';
export default defineComponent( {
name: 'InputWithMenu',
components: {
CdxMenu,
CdxTextInput
},
setup() {
const menu = ref<InstanceType<typeof CdxMenu>>();
const selectedValue = ref<string|number>( '' );
const expanded = ref( false );
const menuItems = [
{ label: 'One', value: '1' },
{ label: 'Two', value: '2', disabled: true },
{ label: 'Three', value: '3' },
{ label: 'Four', value: '4' }
];
function onKeydown( e: KeyboardEvent ) {
// Delegate key events to the menu
menu.value?.delegateKeyNavigation( e );
}
function onClick(): void {
expanded.value = true;
}
return {
menu,
selectedValue,
expanded,
menuItems,
onKeydown,
onClick
};
}
} );
</script>
<style lang="less">
@import ( reference ) '@wikimedia/codex-design-tokens/dist/theme-wikimedia-ui.less';
.cdx-docs-input-with-menu {
// The Menu component is absolutely positioned, so we need `position: relative` here to
// position the menu relative to this div. This ensure the menu will align with the input.
position: relative;
//TODO(T308124): Use existing ".element-with-menu" mixin when available withi the codex build
&__input [ aria-expanded='true' ] {
border-bottom-left-radius: @border-radius-sharp;
border-bottom-right-radius: @border-radius-sharp;
}
}
</style>
Menu with custom menu item display #
- One (value: 1)
- Two (value: 2)
- Three (value: 3)
- Four (value: 4)
vue
<template>
<div class="cdx-docs-input-with-menu-and-footer">
<cdx-text-input
v-model="selectedValue"
class="cdx-docs-input-with-menu-and-footer__input"
:aria-expanded="expanded"
@click="onClick"
@blur="expanded = false"
@keydown="onKeydown"
/>
<cdx-menu
ref="menu"
v-model:selected="selectedValue"
v-model:expanded="expanded"
:menu-items="menuItems"
>
<template #default="{ menuItem }">
{{ menuItem.label }} (value: {{ menuItem.value }})
</template>
</cdx-menu>
</div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import { CdxMenu, CdxTextInput } from '@wikimedia/codex';
export default defineComponent( {
name: 'InputWithMenuCustomItemDisplay',
components: {
CdxMenu,
CdxTextInput
},
setup() {
const menu = ref<InstanceType<typeof CdxMenu>>();
const selectedValue = ref<string|number>( '' );
const expanded = ref( false );
const menuItems = [
{ label: 'One', value: 1 },
{ label: 'Two', value: 2, disabled: true },
{ label: 'Three', value: 3 },
{ label: 'Four', value: 4 }
];
function onKeydown( e: KeyboardEvent ) {
// Delegate key events to the menu
menu.value?.delegateKeyNavigation( e );
}
function onClick(): void {
expanded.value = true;
}
return {
menu,
selectedValue,
expanded,
menuItems,
onKeydown,
onClick
};
}
} );
</script>
<style lang="less">
@import ( reference ) '@wikimedia/codex-design-tokens/dist/theme-wikimedia-ui.less';
.cdx-docs-input-with-menu-and-footer {
// The Menu component is absolutely positioned, so we need `position: relative` here to
// position the menu relative to this div. This ensure the menu will align with the input.
position: relative;
//TODO(T308124): Use existing ".element-with-menu" mixin when available withi the codex build
&__input [ aria-expanded='true' ] {
border-bottom-left-radius: @border-radius-sharp;
border-bottom-right-radius: @border-radius-sharp;
}
}
</style>
Menu with no results message #
If the no-results slot is populated, the Menu component will automatically display it when there are zero menu items.
- No results found
vue
<template>
<div class="cdx-docs-input-with-menu-no-results">
<cdx-text-input
v-model="selectedValue"
class="cdx-docs-input-with-menu__input"
:aria-expanded="expanded"
@click="onClick"
@blur="expanded = false"
@keydown="onKeydown"
/>
<cdx-menu
ref="menu"
v-model:selected="selectedValue"
v-model:expanded="expanded"
:menu-items="menuItems"
>
<template #no-results>
No results found
</template>
</cdx-menu>
</div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import { CdxMenu, CdxTextInput, MenuItemData } from '@wikimedia/codex';
export default defineComponent( {
name: 'InputWithMenuNoResults',
components: {
CdxMenu,
CdxTextInput
},
setup() {
const menu = ref<InstanceType<typeof CdxMenu>>();
const selectedValue = ref<string|number>( '' );
const expanded = ref( false );
const menuItems: MenuItemData[] = [];
function onKeydown( e: KeyboardEvent ) {
// Delegate key events to the menu
menu.value?.delegateKeyNavigation( e );
}
function onClick(): void {
expanded.value = true;
}
return {
menu,
selectedValue,
expanded,
menuItems,
onKeydown,
onClick
};
}
} );
</script>
<style lang="less">
@import ( reference ) '@wikimedia/codex-design-tokens/dist/theme-wikimedia-ui.less';
.cdx-docs-input-with-menu-no-results {
// The Menu component is absolutely positioned, so we need `position: relative` here to
// position the menu relative to this div. This ensure the menu will align with the input.
position: relative;
//TODO(T308124): Use existing ".element-with-menu" mixin when available withi the codex build
&__input [ aria-expanded='true' ] {
border-bottom-left-radius: @border-radius-sharp;
border-bottom-right-radius: @border-radius-sharp;
}
}
</style>
Pending state #
Pending state indicators can be displayed to indicate that menu items are being fetched. Set the pending prop to true to show the inline progress bar and "pending" message, which can be populated via the pending slot. See TypeaheadSearch for a real-world implementation of this.
When there are no menu items (e.g. on an initial search), the inline progress bar and the "pending" message will display.
- Loading results...
vue
<template>
<div class="cdx-docs-input-with-menu-pending">
<cdx-text-input
v-model="selectedValue"
class="cdx-docs-input-with-menu-pending__input"
:aria-expanded="expanded"
@click="expanded = true"
@blur="expanded = false"
@keydown="onKeydown"
/>
<cdx-menu
ref="menu"
v-model:selected="selectedValue"
v-model:expanded="expanded"
:menu-items="[]"
:show-pending="true"
>
<template #pending>
Loading results...
</template>
</cdx-menu>
</div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import { CdxMenu, CdxTextInput } from '@wikimedia/codex';
export default defineComponent( {
name: 'InputWithMenuPending',
components: {
CdxMenu,
CdxTextInput
},
setup() {
const menu = ref<InstanceType<typeof CdxMenu>>();
const selectedValue = ref<string|number>( '' );
const expanded = ref( false );
function onKeydown( e: KeyboardEvent ) {
// Delegate key events to the menu
menu.value?.delegateKeyNavigation( e );
}
return {
menu,
selectedValue,
expanded,
onKeydown
};
}
} );
</script>
<style lang="less">
@import ( reference ) '@wikimedia/codex-design-tokens/dist/theme-wikimedia-ui.less';
.cdx-docs-input-with-menu-pending {
// The Menu component is absolutely positioned, so we need `position: relative` here to
// position the menu relative to this div. This ensure the menu will align with the input.
position: relative;
//TODO(T308124): Use existing ".element-with-menu" mixin when available withi the codex build
&__input [ aria-expanded='true' ] {
border-bottom-left-radius: @border-radius-sharp;
border-bottom-right-radius: @border-radius-sharp;
}
}
</style>
When there are menu items, only the inline progress bar will display.
- One
- Two
- Three
- Four
vue
<template>
<div class="cdx-docs-input-with-menu-pending">
<cdx-text-input
v-model="selectedValue"
class="cdx-docs-input-with-menu-pending__input"
:aria-expanded="expanded"
@click="expanded = true"
@blur="expanded = false"
@keydown="onKeydown"
/>
<cdx-menu
ref="menu"
v-model:selected="selectedValue"
v-model:expanded="expanded"
class="cdx-docs-menu-pending"
:menu-items="menuItems"
:show-pending="true"
>
<template #pending>
Loading results...
</template>
</cdx-menu>
</div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import { CdxMenu, CdxTextInput } from '@wikimedia/codex';
export default defineComponent( {
name: 'InputWithMenuPendingWithItems',
components: {
CdxMenu,
CdxTextInput
},
setup() {
const menu = ref<InstanceType<typeof CdxMenu>>();
const selectedValue = ref<string|number>( '' );
const expanded = ref( false );
const menuItems = [
{ label: 'One', value: '1' },
{ label: 'Two', value: '2', disabled: true },
{ label: 'Three', value: '3' },
{ label: 'Four', value: '4' }
];
function onKeydown( e: KeyboardEvent ) {
// Delegate key events to the menu
menu.value?.delegateKeyNavigation( e );
}
return {
menu,
selectedValue,
expanded,
menuItems,
onKeydown
};
}
} );
</script>
<style lang="less">
@import ( reference ) '@wikimedia/codex-design-tokens/dist/theme-wikimedia-ui.less';
.cdx-docs-input-with-menu-pending {
// The Menu component is absolutely positioned, so we need `position: relative` here to
// position the menu relative to this div. This ensure the menu will align with the input.
position: relative;
//TODO(T308124): Use existing ".element-with-menu" mixin when available withi the codex build
&__input [ aria-expanded='true' ] {
border-bottom-left-radius: @border-radius-sharp;
border-bottom-right-radius: @border-radius-sharp;
}
}
</style>
Usage #
Props #
| Prop name | Description | Type | Default |
|---|---|---|---|
menuItems(required) | Menu items. See the MenuItemData type. | MenuItemData[] | |
selected(required) | Value of the selected menu item, or undefined if no item is selected. Must be bound with v-model:selected.The property should be initialized to null rather than using a falsy value. | string|number|null | |
expanded(required) | Whether the menu is expanded. Must be bound with v-model:expanded. | boolean | |
showPending | Whether to display pending state indicators. Meant to indicate that new menu items are being fetched or computed. When true, the menu will expand if not already expanded, and an inline progress bar will display. If there are no menu items yet, a message can be displayed in the pending slot, e.g. "Loading results". | boolean | false |
showThumbnail | Whether menu item thumbnails (or a placeholder icon) should be displayed. | boolean | false |
boldLabel | Whether to bold menu item labels. | boolean | false |
hideDescriptionOverflow | Whether to hide description text overflow via an ellipsis. | boolean | false |
searchQuery | The search query to be highlighted within the menu items' titles. | string | '' |
showNoResultsSlot | Whether to show the no-results slot content.The Menu component automatically shows this slot when there is content in the no-results slot and there are zero menu items. However, some components may need to customize this behavior, e.g. to show the slot even when there is at least one menu item. This prop can be used to override the default Menu behavior.Possible values: null (default): the no-results slot will display only if there are zero menu items. true: the no-results slot will display, regardless of number of menu items. false: the no-results slot will not display, regardless of number of menu items. | boolean|null | null |
Methods #
| Method name | Description | Signature |
|---|---|---|
getHighlightedMenuItem | Get the highlighted menu item, if any. | Returns: MenuItemDataWithId|null The highlighted menu item, or null if no item is highlighted. |
clearActive | Ensure no menu item is active. This unsets the active item if there is one. | Returns: void |
delegateKeyNavigation | Handles all necessary keyboard navigation. The parent component should listen for keydown events on its focusable element, and pass those events to this method. Events for arrow keys, tab and enter are handled by this method. If a different key was pressed, this method will return false to indicate that it didn't handle the event. | Params:
boolean Whether the event was handled |
Events #
| Event name | Properties | Description |
|---|---|---|
menu-item-click | menuItem MenuItemDataWithId - The menu item that was clicked | When a menu item is clicked. Typically, components with menus will respond to the selected value change, but occasionally, a component might want to react specifically when a menu item is clicked. |
update:selected | selectedValue string | number | null - The .value property of the selected menu item, or null if no item is selected. | When the selected menu item changes. |
update:expanded | newValue boolean - The new expanded state (true for open, false for closed) | When the menu opens or closes. |
menu-item-keyboard-navigation | highlightedMenuItem MenuItemDataWithId - The menu item was highlighted | When a menu item is highlighted via keyboard navigation. |
Slots #
| Name | Description | Bindings |
|---|---|---|
| pending | Message to indicate pending state. | |
| no-results | Message to show if there are no menu items to display. | |
| default | Display of an individual item in the menu | active boolean - Whether the current item is visually active |