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

Menu

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,
});

MenuItem

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

Name	Module	Package
FoundationElement	/src/foundation-element/foundation-element.js

Fields

Name	Privacy	Type	Default	Description	Inherited From
$presentation	public	ComponentPresentation or null		A property which resolves the ComponentPresentation instance for the current component.	FoundationElement
template	public	ElementViewTemplate or void or null		Sets 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
styles	public	ElementStyles or void or null		Sets 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

Name	Privacy	Description	Parameters	Return	Inherited From
focus	public	Focuses the first item in the menu.		void
collapseExpandedItem	public	Collapses any expanded menu items.		void
templateChanged	protected			void	FoundationElement
stylesChanged	protected			void	FoundationElement

Slots

Name	Description
	The default slot for the menu items

---

Variables

Name	Description	Type
MenuItemRole	Menu items roles.	{ menuitem: "menuitem", menuitemcheckbox: "menuitemcheckbox", menuitemradio: "menuitemradio", }

---

class: MenuItem

Superclass

Name	Module	Package
FoundationElement	/src/foundation-element/foundation-element.js

Fields

Name	Privacy	Type	Default	Description	Inherited From
disabled	public	boolean		The disabled state of the element.
expanded	public	boolean		The expanded state of the element.
role	public	MenuItemRole		The role of the element.
checked	public	boolean		The checked value of the element.
$presentation	public	ComponentPresentation or null		A property which resolves the ComponentPresentation instance for the current component.	FoundationElement
template	public	ElementViewTemplate or void or null		Sets 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
styles	public	ElementStyles or void or null		Sets 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

Name	Privacy	Description	Parameters	Return	Inherited From
templateChanged	protected			void	FoundationElement
stylesChanged	protected			void	FoundationElement

Events

Name	Type	Description	Inherited From
expanded-change		Fires a custom 'expanded-change' event when the expanded state changes
change		Fires a custom 'change' event when a non-submenu item with a role of `menuitemcheckbox`, `menuitemradio`, or `menuitem` is invoked

Attributes

Name	Field	Inherited From
	disabled
	expanded
role	role
	checked

CSS Parts

Name	Description
input-container	The element representing the visual checked or radio indicator
checkbox	The element wrapping the `menuitemcheckbox` indicator
radio	The element wrapping the `menuitemradio` indicator
content	The element wrapping the menu item content
expand-collapse-glyph-container	The element wrapping the expand collapse element
expand-collapse	The expand/collapse element
submenu-region	The container for the submenu, used for positioning

Slots

Name	Description
checked-indicator	The checked indicator
radio-indicator	The radio indicator
start	Content which can be provided before the menu item content
end	Content which can be provided after the menu item content
	The default slot for menu item content
expand-collapse-indicator	The expand/collapse indicator
submenu	Used to nest menu's within menu items

---

Additional resources

• Component explorer examples
• Component technical specification
• W3C Component Aria Practices