Codex Direction:
MenuItem #
Item within a Menu component.
A value must be provided, and various optional elements can be displayed:
- A human-readable label
- A description
- A thumbnail or icon
Alternately, the entire content and layout of the menu item can be customized via the default slot.
For search results, the search query can be visually differentiated within the result title.
WARNING
This is not a standalone component, nor will it typically be directly used. It's intended for use by the Menu component, which will provide it with props and menu state information. See Menu for more details.
Demos #
Note that these demos do not properly show some interactive states of menu items (like active or hovered/highlighted), since they display menu items as standalone or as part of an always-expanded, detached menu. To see the full interactivity of menu items, check out a component that contains a menu, like Select, Lookup, or TypeaheadSearch.
Configurable #
Note that manually hovering over or selecting this menu item is disabled, the configuration options to set these states should be used.
<cdx-menu-item label="Item label" :icon="cdxIconGlobe" description="Description text" />| Name | Value |
|---|---|
| Props | |
disabled | |
selected | |
active | |
highlighted | |
label | |
match | |
icon | |
description | |
searchQuery | |
boldLabel | |
hideDescriptionOverflow | |
Note: For icon properties, the relevant icon also needs to be imported from the @wikimedia/codex-icons package. See the usage documentation for more information. | |
Default #
vue
<template>
<cdx-menu-item
v-bind="menuItem"
/>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { CdxMenuItem, MenuItemDataWithId } from '@wikimedia/codex';
const menuItem : MenuItemDataWithId = {
value: 5921,
label: 'Color',
id: 'menu-item-default'
};
export default defineComponent( {
name: 'MenuItemDefault',
components: { CdxMenuItem },
setup() {
return {
menuItem
};
}
} );
</script>
With description and bold label #
vue
<template>
<cdx-menu-item
v-bind="menuItem"
:bold-label="true"
/>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { CdxMenuItem, MenuItemDataWithId } from '@wikimedia/codex';
const menuItem : MenuItemDataWithId = {
value: 5921,
label: 'Color',
description: 'visual perception of light wavelengths',
id: 'menu-item-with-description'
};
export default defineComponent( {
name: 'MenuItemWithDescription',
components: { CdxMenuItem },
setup() {
return {
menuItem
};
}
} );
</script>
With link #
If a url property is included, the menu item will be wrapped in an anchor tag.
vue
<template>
<cdx-menu-item
v-bind="menuItem"
/>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { CdxMenuItem, MenuItemDataWithId } from '@wikimedia/codex';
const menuItem : MenuItemDataWithId = {
value: 5921,
label: 'Color',
url: 'https://en.wikipedia.org/wiki/Color',
description: 'visual perception of light wavelengths',
id: 'menu-item-with-url'
};
export default defineComponent( {
name: 'MenuItemWithUrl',
components: { CdxMenuItem },
setup() {
return {
menuItem
};
}
} );
</script>
With icon #
vue
<template>
<cdx-menu-item
v-bind="menuItem"
/>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { CdxMenuItem, MenuItemDataWithId } from '@wikimedia/codex';
import { cdxIconTag } from '@wikimedia/codex-icons';
const menuItem : MenuItemDataWithId = {
value: 5921,
label: 'Color',
description: 'visual perception of light wavelengths',
icon: cdxIconTag,
id: 'menu-item-with-icon'
};
export default defineComponent( {
name: 'MenuItemWithIcon',
components: { CdxMenuItem },
setup() {
return {
menuItem
};
}
} );
</script>
With thumbnail #
vue
<template>
<cdx-menu-item
v-bind="menuItem"
:show-thumbnail="true"
/>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { CdxMenuItem, MenuItemDataWithId } from '@wikimedia/codex';
const menuItem : MenuItemDataWithId = {
value: 5921,
label: 'Color',
url: 'https://en.wikipedia.org/wiki/Color',
description: 'visual perception of light wavelengths',
thumbnail: {
width: 200,
height: 150,
url: '//upload.wikimedia.org/wikipedia/commons/thumb/2/21/64_365_Color_Macro_%285498808099%29.jpg/200px-64_365_Color_Macro_%285498808099%29.jpg'
},
id: 'menu-item-with-thumbnail'
};
export default defineComponent( {
name: 'MenuItemWithThumbnail',
components: { CdxMenuItem },
setup() {
return {
menuItem
};
}
} );
</script>
With search query highlighted #
When a menu item displays a search result, the current search query can be provided (along with the highlightQuery prop) and it will be visually differentiated within the menu item's title. The search query text will have a normal font weight, while the rest of the title will be bold, which is meant to bring attention to the available suggestions based on the current search query.
In the example below, the search query is "Co".
vue
<template>
<cdx-menu-item
v-bind="menuItem"
search-query="Co"
:highlight-query="true"
/>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { CdxMenuItem, MenuItemDataWithId } from '@wikimedia/codex';
const menuItem : MenuItemDataWithId = {
value: 5921,
label: 'Color',
url: 'https://en.wikipedia.org/wiki/Color',
description: 'visual perception of light wavelengths',
id: 'menu-item-highlight-query'
};
export default defineComponent( {
name: 'MenuItemHighlightQuery',
components: { CdxMenuItem },
setup() {
return {
menuItem
};
}
} );
</script>
With search query match #
For search results, a match property may be included that represents the text related to that item that matched the search query (e.g. a Wikidata alias). The match will be displayed after the label. In the example below, the search query is "felis margarita," an alias of the Wikidata item "sand cat."
vue
<template>
<cdx-menu-item
v-bind="menuItem"
search-query="felis margarita"
/>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { CdxMenuItem, MenuItemDataWithId } from '@wikimedia/codex';
const menuItem : MenuItemDataWithId = {
value: 'Q175329',
label: 'sand cat',
match: '(Felis margarita)',
description: 'species of the only cat living foremost in true deserts',
id: 'menu-item-with-match'
};
export default defineComponent( {
name: 'MenuItemWithMatch',
components: { CdxMenuItem },
setup() {
return {
menuItem
};
}
} );
</script>
With multiple languages #
In addition to simple strings, the label, description, and match props can be objects with a string value and an associated language code. The lang attribute for that string will be set in the markup. The example below demonstrates a search result in a Greek interface for the English word "moon."
vue
<template>
<cdx-menu-item
v-bind="menuItem"
search-query="moon"
/>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { CdxMenuItem, MenuItemDataWithId } from '@wikimedia/codex';
const menuItem : MenuItemDataWithId = {
value: 'Q405',
label: 'Σελήνη',
match: '(moon)',
description: 'ο μοναδικός φυσικός δορυφόρος της Γης',
language: {
label: 'el',
match: 'en',
description: 'el'
},
id: 'menu-item-multiple-langs'
};
export default defineComponent( {
name: 'MenuItemMultipleLangs',
components: { CdxMenuItem },
setup() {
return {
menuItem
};
}
} );
</script>
With long title and search query highlighted #
vue
<template>
<cdx-menu-item
v-bind="menuItem"
search-query="Donaudampfschiffahrtselektrizit"
:highlight-query="true"
/>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { CdxMenuItem, MenuItemDataWithId } from '@wikimedia/codex';
// See https://phabricator.wikimedia.org/T280982.
const menuItem : MenuItemDataWithId = {
value: 2201357,
label: 'Donaudampfschiffahrtselektrizitätenhauptbetriebswerkbauunterbeamtengesellschaft',
url: 'https://en.wikipedia.org/wiki/Donaudampfschiffahrtselektrizit%C3%A4tenhauptbetriebswerkbauunterbeamtengesellschaft',
description: 'Arguably the longest German word',
id: 'menu-item-long-text'
};
export default defineComponent( {
name: 'MenuItemLongText',
components: { CdxMenuItem },
setup() {
return {
menuItem
};
}
} );
</script>
With description text overflow hidden #
vue
<template>
<cdx-menu-item
v-bind="menuItem"
search-query="Donaudampfschiffahrtselektrizit"
:highlight-query="true"
:hide-description-overflow="true"
/>
</template>
<script lang="ts">
import { defineComponent } from 'vue';
import { CdxMenuItem, MenuItemDataWithId } from '@wikimedia/codex';
const menuItem : MenuItemDataWithId = {
value: 2201357,
label: 'Donaudampfschiffahrtselektrizitätenhauptbetriebswerkbauunterbeamtengesellschaft',
url: 'https://en.wikipedia.org/wiki/Donaudampfschiffahrtselektrizit%C3%A4tenhauptbetriebswerkbauunterbeamtengesellschaft',
description: 'Arguably the longest German word, which again, is Donaudampfschiffahrtselektrizitätenhauptbetriebswerkbauunterbeamtengesellschaft',
id: 'menu-item-hide-overflow'
};
export default defineComponent( {
name: 'MenuItemHideOverflow',
components: { CdxMenuItem },
setup() {
return {
menuItem
};
}
} );
</script>
Within a list #
- Co
- Colorvisual perception of light wavelengths
- Coloradostate of the United States of America
- Colorado Springs, Coloradocounty seat of El Paso County, Colorado, United States
- Colorado Rivermajor river in the western United States and Mexico
- Colour revolutionpolitical term associated with democratization
- Color depthrange of colors in a display
- Color temperatureproperty of light sources related to black-body radiation
- Color photographythat uses media capable of representing colors
- Colorado State Universitypublic research university in Fort Collins, Colorado, USA
vue
<template>
<cdx-menu
v-model:selected="selection"
:expanded="true"
:menu-items="searchResults"
:show-thumbnail="true"
:search-query="searchQuery"
:highlight-query="true"
/>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import { CdxMenu } from '@wikimedia/codex';
import searchResults from './searchResults';
export default defineComponent( {
name: 'MenuItems',
components: { CdxMenu },
setup() {
const selection = ref( '' );
return {
selection,
searchResults,
searchQuery: 'Co'
};
}
} );
</script>
With graphemes #
- ইতালিদক্ষিণাঞ্চলীয় ইউরোপের দেশ
- ইতালির বিশ্ব ঐতিহ্যবাহী স্থানসমূহের তালিকা
- ইতালীয় ভাষা
- ইতালি জাতীয় ফুটবল দল
- ইতালির সড়ক সংকেতসমূহ
- ইতালিতে কোভিড-১৯ এর বৈশ্বিক মহামারীইতালিতে ভাইরাসঘটিত চলমান কোভিড-১৯ এর বৈশ্বিক মহামারী
- ইতালীয় ফুটবল ফেডারেশন
- ইতালি–ফিলিপাইন সম্পর্কইতালি ও ফিলিপাইন রাষ্ট্রদ্বয়ের মধ্যকার দ্বিপাক্ষিক সম্পর্ক
- ইতালীয় নব্যবাস্তববাদ
- ইতালিতে উন্মুক্ত প্রবেশাধিকার
vue
<template>
<cdx-menu
v-model:selected="selection"
:expanded="true"
:menu-items="searchResults"
:show-thumbnail="true"
:search-query="searchQuery"
:highlight-query="true"
/>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import { CdxMenu } from '@wikimedia/codex';
import searchResults from './searchResultsGraphemes';
// This demo serves to demonstrate how the highlighting mechanism in the
// SearchResultTitle component handles languages with characters represented by
// more than one Unicode scalar values.
//
// See https://phabricator.wikimedia.org/T277256 and
// https://phabricator.wikimedia.org/T35242 for details.
export default defineComponent( {
name: 'MenuItemsGraphemes',
components: { CdxMenu },
setup() {
const selection = ref( '' );
return {
selection,
searchResults,
searchQuery: 'ইতাল'
};
}
} );
</script>
Usage #
Props #
| Prop name | Description | Type | Default |
|---|---|---|---|
id(required) | ID for HTML id attribute. | string | |
value(required) | The value provided to the parent menu component when this menu item is selected. | string|number | |
disabled | Whether the menu item is disabled. | boolean | false |
selected | Whether this menu item is selected. | boolean | false |
active | Whether this menu item is being pressed. | boolean | false |
highlighted | Whether this menu item is hovered over or highlighted via keyboard navigation. | boolean | false |
label | Label for the menu item. If this isn't provided, the value will be displayed instead. | string | '' |
match | Text that matches current search query. Only used for search results and will be displayed after the label. | string | '' |
url | URL for the menu item. If provided, the content of the menu item will be wrapped in an anchor tag. | string | '' |
icon | Icon for the menu item. | Icon | '' |
showThumbnail | Whether a thumbnail (or a placeholder icon) should be displayed. | boolean | false |
thumbnail | Thumbnail for the menu item. | Thumbnail|null | null |
description | Description of the menu item. | string|null | '' |
searchQuery | The search query to be highlighted within the menu item's title. | string | '' |
boldLabel | Whether to bold menu item labels. | boolean | false |
hideDescriptionOverflow | Whether to hide description text overflow via an ellipsis. | boolean | false |
language | Optional language codes for label, match, and description. If included, that language code will be added as a lang attribute to the element wrapping that text node. | MenuItemLanguageData | () => { return {}; } |
Events #
| Event name | Properties | Description |
|---|---|---|
change | menuState MenuState - State to change setState boolean - Whether to set that state to this menu item | Emitted when the menu item becomes selected, active or highlighted in response to user interaction. Handled in the Menu component. |
Slots #
| Name | Description | Bindings |
|---|---|---|
| default | Custom menu item content. |