Skip to main content
Version: Current

Web Components - 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 alpha-menu-items and slotted content with a role of menuitem, menuitemcheckbox, or menuitemradio can receive keyboard support.

Set-up

import { provideDesignSystem, alphaMenu, alphaMenuItem } from '@genesislcap/alpha-design-system';

provideDesignSystem().register(alphaMenu(), alphaMenuItem());

Parameters

Methods

You can use the following method when you declare an <alpha-menu>:

NameDescription
collapseExpandedItem()Collapses all expended menus

In order to use the menu component, you need to create the menu items for the user to interact with. You create this using <alpha-menu-item>. You can define the following attributes for an <alpha-menu-item>:

NameTypeDescription
disabledbooleanDisables the menu-item
expandedbooleanIf this menu-item has sub-menus, it starts expanded. Default: false
rolestringChanges the displayed item into a menu item, a radio or a checkbox. Values can be: menuitem, menuitemcheckbox, menuitemradio. Default: menuitem
checkedbooleanused with role. Checks the item. Default: false

Events

In order to interact with this component, you need to use events. These events can trigger specific functions in your application:

NameDescription
changeFires the @change event when a menu or sub-menu is clicked or invoked via keyboard
clickFires the @click event when a menu or sub-menu is clicked. Use @change to enable keyboard event
expanded-changeFires the @expanded-change event when an item is expanded or collapsed

Usage

Below are some examples of how to use the <alpha-menu> component. All the examples use the alpha-design-system. If you are using any other design system, change the declaration of this component accordingly.

  • Example 1: a menu with three items
Example 1
<alpha-menu>
<alpha-menu-item>Menu item 1</alpha-menu-item>
<alpha-menu-item>Menu item 2</alpha-menu-item>
<alpha-menu-item>Menu item 3</alpha-menu-item>
</alpha-menu>
  • Example 2: a menu with 4 items, with the 4th item having more 3 items
Example 2
<alpha-menu>
<alpha-menu-item>Menu item 1</alpha-menu-item>
<alpha-menu-item>Menu item 2</alpha-menu-item>
<alpha-menu-item>Menu item 3</alpha-menu-item>
<alpha-menu-item>
Menu item 4
<alpha-menu>
<alpha-menu-item>Menu item 4.1</alpha-menu-item>
<alpha-menu-item>Menu item 4.2</alpha-menu-item>
<alpha-menu-item>Menu item 4.3</alpha-menu-item>
</alpha-menu>
</alpha-menu-item>
</alpha-menu>
  • Example 3: a menu with three items, first as a checkbox, second as a radio and third with a checked checkbox
Example 3
<alpha-menu>
<alpha-menu-item role="menuitemcheckbox">Menu item 1</alpha-menu-item>
<alpha-menu-item role="menuitemradio">Menu item 2</alpha-menu-item>
<alpha-menu-item role="menuitemcheckbox" checked>Menu item 3</alpha-menu-item>
</alpha-menu>

Trigger an action

The <alpha-menu> and <alpha-menu-item>components have 3 custom events that can be used.

  1. Create a function functionName1(), functionName2() and functionName3() in the class of the component:
export class TEMPLATE extends GenesisElement {
...
functionName1(){
// Write an action here
}
functionName2(){
// Write an action here
}
functionName3(){
// Write an action here
}
...
}
  1. Use the event @click, @change or @expanded-change to call your function:
    ...
<alpha-menu @change=${() => console.log("You changed me")>
<alpha-menu-item @click=${x => x.functionName1()}>Menu item 1</alpha-menu-item>
<alpha-menu-item @click=${x => x.functionName2()}>Menu item 3</alpha-menu-item>
<alpha-menu-item @expanded-change=${x => x.functionName3()}>
Menu item 4
<alpha-menu>
<alpha-menu-item>Menu item 4.1</alpha-menu-item>
</alpha-menu>
</alpha-menu-item>
</alpha-menu>
...

Remember that if your main <alpha-menu> has an event attached, then it will replicate to all components inside it. In this example, funtionName1() will be called twice:

<alpha-menu  @click=${x => x.functionName1()}>
<alpha-menu-item @click=${x => x.functionName1()}>Menu item 1</alpha-menu-item>
</alpha-menu>

Try yourself

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

Use cases

  • Dropdown menu control triggered by a button click e.g. settings menu
  • A contextual menu triggered by a right-click
  • Filtering and Sorting
  • Navigation

Additional resources