Skip to main content
Version: 1.x

fast-menu

As defined by the W3C:

A menu is a widget that offers a list of choices to the user, such as a set of actions or functions. Menu widgets behave like native operating system menus, such as the menus that pull down from the menubars commonly found at the top of many desktop application windows. A menu is usually opened, or made visible, by activating a menu button, choosing an item in a menu that opens a sub menu, or by invoking a command, such as Shift + F10 in Windows, that opens a context specific menu. When a user activates a choice in a menu, the menu usually closes unless the choice opened a submenu.

While any DOM content is permissible as a child of the menu, only fast-menu-item's and slotted content with a role of menuitem, menuitemcheckbox, or menuitemradio will receive keyboard support.

fast-menu applies fast-menu-item's startColumnCount property based on an evaluation of all of the fast-menu-items so the content text vertically aligns across all fast-menu-items. If any fast-menu-item does not have a roll of checkbox or radio or the start slot is not passed, startColumnCount is set to 0 which applies a indent-0 class to all the fast-menu-items. If any fast-menu-item has a roll of checkbox or radio or the start slot exists, startColumnCount is set to 1 which applies a indent-1 class to all the fast-menu-items. Or if any fast-menu-item has a roll of checkbox or radio and the start slot exists, startColumnCount is set to 2 which applies a indent-2 class to all the fast-menu-items.

Setup

Basic Setup

import {
provideFASTDesignSystem,
fastMenu,
fastMenuItem
} from "@microsoft/fast-components";

provideFASTDesignSystem()
.register(
fastMenu(),
fastMenuItem()
);

Customizing Indicators and Glyphs

import {
provideFASTDesignSystem,
fastMenu,
fastMenuItem
} from "@microsoft/fast-components";

provideFASTDesignSystem()
.register(
fastMenu(),
fastMenuItem({
expandCollapseGlyph: `...your expand/collapse glyph...`,
checkboxIndicator: `...your checkbox indicator...`,
radioIndicator: `...your radio indicator...`,
})
);

Usage

Basic Usage

Live Editor
<fast-menu>
    <fast-menu-item>Menu item 1</fast-menu-item>
    <fast-menu-item>Menu item 2</fast-menu-item>
    <fast-menu-item>Menu item 3</fast-menu-item>
    <fast-divider></fast-divider>
    <fast-menu-item role="menuitemradio">Menu item 4</fast-menu-item>
    <fast-menu-item role="menuitemradio">Menu item 5</fast-menu-item>
</fast-menu>
Result
Loading...

Nested Menus

Live Editor
<fast-menu>
    <fast-menu-item>
        Menu item 1
        <fast-menu>
            <fast-menu-item>Menu item 1.1</fast-menu-item>
            <fast-menu-item>Menu item 1.2</fast-menu-item>
            <fast-menu-item>Menu item 1.3</fast-menu-item>
        </fast-menu>
    </fast-menu-item>
    <fast-menu-item>
        Menu item 2
        <fast-menu>
            <fast-menu-item>Menu item 2.1</fast-menu-item>
            <fast-menu-item>Menu item 2.2</fast-menu-item>
            <fast-menu-item>Menu item 2.3</fast-menu-item>
        </fast-menu>
    </fast-menu-item>
    <fast-menu-item>
        Menu item 3
        <fast-menu>
            <fast-menu-item>Menu item 3.1</fast-menu-item>
            <fast-menu-item>Menu item 3.2</fast-menu-item>
            <fast-menu-item>Menu item 3.3</fast-menu-item>
        </fast-menu>
    </fast-menu-item>
</fast-menu>
Result
Loading...

Create your own design

import { Menu, menuTemplate as template } from "@microsoft/fast-foundation";
import { menuStyles as styles } from "./my-menu.styles";

export const myMenu = Menu.compose({
baseName: "menu",
template,
styles,
});
import {
MenuItem,
MenuItemOptions,
menuItemTemplate as template,
} from "@microsoft/fast-foundation";
import { menuItemStyles as styles } from "./my-menu-item.styles";

export const myMenuItem = MenuItem.compose<MenuItemOptions>({
baseName: "menu-item",
template,
styles,
expandCollapseGlyph: `...default expand/collapse glyph...`,
checkboxIndicator: `...default checkbox indicator...`,
radioIndicator: `...default radio indicator...`,
});

API

class: Menu

Superclass

NameModulePackage
FoundationElement/src/foundation-element/foundation-element.js

Fields

NamePrivacyTypeDefaultDescriptionInherited From
$presentationpublicComponentPresentation or nullA property which resolves the ComponentPresentation instance for the current component.FoundationElement
templatepublicElementViewTemplate or void or nullSets the template of the element instance. When undefined, the element will attempt to resolve the template from the associated presentation or custom element definition.FoundationElement
stylespublicElementStyles or void or nullSets the default styles for the element instance. When undefined, the element will attempt to resolve default styles from the associated presentation or custom element definition.FoundationElement

Methods

NamePrivacyDescriptionParametersReturnInherited From
focuspublicFocuses the first item in the menu.void
collapseExpandedItempublicCollapses any expanded menu items.void
templateChangedprotectedvoidFoundationElement
stylesChangedprotectedvoidFoundationElement

Slots

NameDescription
The default slot for the menu items

Variables

NameDescriptionType
MenuItemRoleMenu items roles.{ menuitem: "menuitem", menuitemcheckbox: "menuitemcheckbox", menuitemradio: "menuitemradio", }

class: MenuItem

Superclass

NameModulePackage
FoundationElement/src/foundation-element/foundation-element.js

Fields

NamePrivacyTypeDefaultDescriptionInherited From
disabledpublicbooleanThe disabled state of the element.
expandedpublicbooleanThe expanded state of the element.
rolepublicMenuItemRoleThe role of the element.
checkedpublicbooleanThe checked value of the element.
$presentationpublicComponentPresentation or nullA property which resolves the ComponentPresentation instance for the current component.FoundationElement
templatepublicElementViewTemplate or void or nullSets the template of the element instance. When undefined, the element will attempt to resolve the template from the associated presentation or custom element definition.FoundationElement
stylespublicElementStyles or void or nullSets the default styles for the element instance. When undefined, the element will attempt to resolve default styles from the associated presentation or custom element definition.FoundationElement

Methods

NamePrivacyDescriptionParametersReturnInherited From
templateChangedprotectedvoidFoundationElement
stylesChangedprotectedvoidFoundationElement

Events

NameTypeDescriptionInherited From
expanded-changeFires a custom 'expanded-change' event when the expanded state changes
changeFires a custom 'change' event when a non-submenu item with a role of `menuitemcheckbox`, `menuitemradio`, or `menuitem` is invoked

Attributes

NameFieldInherited From
disabled
expanded
rolerole
checked

CSS Parts

NameDescription
input-containerThe element representing the visual checked or radio indicator
checkboxThe element wrapping the `menuitemcheckbox` indicator
radioThe element wrapping the `menuitemradio` indicator
contentThe element wrapping the menu item content
expand-collapse-glyph-containerThe element wrapping the expand collapse element
expand-collapseThe expand/collapse element
submenu-regionThe container for the submenu, used for positioning

Slots

NameDescription
checked-indicatorThe checked indicator
radio-indicatorThe radio indicator
startContent which can be provided before the menu item content
endContent which can be provided after the menu item content
The default slot for menu item content
expand-collapse-indicatorThe expand/collapse indicator
submenuUsed to nest menu's within menu items

Additional resources