Skip to main content
HomeComponentsMenu
warning
This is a beta release of the Quantum web libraries
Please be careful when using them in production, as they may contain bugs, unstable breaking changes, and incomplete features.
Go to the latest version

Menu

The Menu is an UI component that displays a list of items vertically. It's commonly used to group related options or actions together. You can use it within various components like Dropdown, Drawer, and Split Button to organize content or actions in a straightforward and accessible way.

By default, a Menu will handle automatically the active menu item based on user interaction thanks to the enable-auto-active prop set by default to true.

There are two ways to use this component:

info

All menu items and submenu items must have an id attribute for the features to work properly.

Using slots​

You can pass elements like MenuItem, SubmenuItem, and their associated components as slot to construct a MenuItemList. This provides enhanced control over the layout and content, allowing for more tailored and flexible menu designs.

Single level menu​

Menu ItemMenu ItemMenu Item
<qtm-menu-item-list>
  <qtm-menu-item id="menu1">
    <qtm-menu-item-label>
      <qtm-icon icon="account_circle"></qtm-icon>
      <qtm-typography>Menu Item</qtm-typography>
    </qtm-menu-item-label>
  </qtm-menu-item>
  <qtm-menu-item id="menu2">
    <qtm-menu-item-label>
      <qtm-icon icon="account_circle"></qtm-icon>
      <qtm-typography>Menu Item</qtm-typography>
    </qtm-menu-item-label>
  </qtm-menu-item>
  <qtm-menu-item id="menu3">
    <qtm-menu-item-label>
      <qtm-icon icon="account_circle"></qtm-icon>
      <qtm-typography>Menu Item</qtm-typography>
    </qtm-menu-item-label>
  </qtm-menu-item>
</qtm-menu-item-list>

Multi-level menu​

For menu item with submenu items, a collapsed icon should also be displayed on the right side of menu item label. To select a suitable icon, please refer to the Icon documentation.

Menu ItemMenu ItemMenu ItemSubmenu ItemSubmenu ItemSubmenu Item
<qtm-menu-item-list>
  <qtm-menu-item id="menu1">
    <qtm-menu-item-label>
      <qtm-icon icon="account_circle"></qtm-icon>
      <qtm-typography>Menu Item</qtm-typography>
    </qtm-menu-item-label>
  </qtm-menu-item>
  <qtm-menu-item id="menu2">
    <qtm-menu-item-label>
      <qtm-icon icon="account_circle"></qtm-icon>
      <qtm-typography>Menu Item</qtm-typography>
    </qtm-menu-item-label>
  </qtm-menu-item>
  <qtm-menu-item id="menu3">
    <qtm-menu-item-label>
      <qtm-icon icon="account_circle"></qtm-icon>
      <qtm-typography>Menu Item</qtm-typography>
      <qtm-icon icon="keyboard_arrow_up"></qtm-icon>
    </qtm-menu-item-label>
    <qtm-submenu-item-list>
      <qtm-submenu-item id="submenu1">Submenu Item</qtm-submenu-item>
      <qtm-submenu-item id="submenu2">Submenu Item</qtm-submenu-item>
      <qtm-submenu-item id="submenu3">Submenu Item</qtm-submenu-item>
    </qtm-submenu-item-list>
  </qtm-menu-item>
</qtm-menu-item-list>

Using items prop​

You can also use the items prop to generate the menu item list dynamically. This prop has the following format:

type MenuItemType = {
  label: string,
  id: string,
  icon?: string | IconProps,
  children?: [
    {
      label: string,
      id: string,
    }
  ],
};

Single level menu​

<script>
  const items=[
    { label: 'Menu item', id: 'menu1', icon: 'account_circle' },
    { label: 'Menu item', id: 'menu2', icon: 'account_circle' },
    { label: 'Menu item', id: 'menu3', icon: 'account_circle' },
  ]
  document.getElementById("menu-list").items = items
</script>

<qtm-menu-item-list id="menu-list"></qtm-menu-item-list>

Multi-level menu​

For menu items that contain submenu items, a collapsed icon will be automatically displayed on the right side of the menu label. When a menu item with a submenu is clicked, the icon will dynamically expand or collapse.

<script>
  const items=[
    {label: "Menu item", id: "menu1", icon: "account_circle"},
    {label: "Menu item", id: "menu2", icon: "account_circle"},
    {
      label: "Menu item", id: "menu3", icon: "account_circle",
      children: [
        { label: 'Submenu item', id: 'submenu1' },
        { label: 'Submenu item', id: 'submenu2' },
        { label: 'Submenu item', id: 'submenu3' },
      ],
    },
  ]
  document.getElementById("menu-list").items = items
</script>

<qtm-menu-item-list id="menu-list"></qtm-menu-item-list>

Multi-level menu with custom icon​

To select an appropriate icon, please consult the Icon component documentation.

You can include an icon in the items property by adding either the icon name or an icon object with the following interface:

interface IconProps = {
  icon: string,
  classes?: string,
  lib?: IconLibType,
  size?: IconSizeType,
  variant?: IconVariantType,
};
<script>
  const items=[
    {label: "Menu item", id: "menu1", icon: {icon: 'applied_settings', lib:"business"}},
    {label: "Menu item", id: "menu2", icon: {icon: 'applied_settings', lib:"business"}},
    {
      label: "Menu item", id: "menu3",
      icon: { icon: 'applied_settings', lib:"business"}
      children: [
        { label: 'Submenu item', id: 'submenu1' },
        { label: 'Submenu item', id: 'submenu2' },
        { label: 'Submenu item', id: 'submenu3' },
      ],
    },
  ]
  document.getElementById("menu-list").items = items
</script>

<qtm-menu-item-list id="menu-list"></qtm-menu-item-list>

Sizes​

The menu item lists come in three size: small, medium (default) and large.

Small
Medium
Large
<script>
  const items=[{label: "Menu item", id: "menu1", icon: "account_circle"},...]
  ["menu-list1", "menu-list2", "menu-list3"].forEach(listId =>
    document.getElementById(listId).items = items
  )
</script>

<qtm-menu-item-list id="menu-list1" size="small"></qtm-menu-item-list>
<qtm-menu-item-list id="menu-list2" size="medium"></qtm-menu-item-list>
<qtm-menu-item-list id="menu-list3" size="large"></qtm-menu-item-list>

Managing items​

All the props listed below can be applied directly to the MenuItemList component, either using the slots or using the items prop method.

enable-auto-active​

Setting the enable-auto-active prop to true (default value) will automatically activate the active state of both menu items and submenu items when they are clicked or when the active-id prop value has changed.

On the other hand, setting it to false will require manual management of the active state.

warning

When enable-auto-active is set to false, handling the active state is not compatible with the items prop usage.

info

For a SubmenuItem to be active, its MenuItem parent must also have the active prop.

Menu ItemMenu ItemMenu ItemSubmenu ItemSubmenu ItemSubmenu Item
<qtm-menu-item-list enable-auto-active="false">
  <qtm-menu-item id="menu1">
    <qtm-menu-item-label>
      <qtm-icon icon="account_circle"></qtm-icon>
      <qtm-typography>Menu Item</qtm-typography>
    </qtm-menu-item-label>
  </qtm-menu-item>
  <qtm-menu-item id="menu2">
    <qtm-menu-item-label>
      <qtm-icon icon="account_circle"></qtm-icon>
      <qtm-typography>Menu Item</qtm-typography>
    </qtm-menu-item-label>
  </qtm-menu-item>
  <qtm-menu-item id="menu3" active>
    <qtm-menu-item-label>
      <qtm-icon icon="account_circle"></qtm-icon>
      <qtm-typography>Menu Item</qtm-typography>
      <qtm-icon icon="keyboard_arrow_up"></qtm-icon>
    </qtm-menu-item-label>
    <qtm-submenu-item-list>
      <qtm-submenu-item id="submenu1">Submenu Item</qtm-submenu-item>
      <qtm-submenu-item id="submenu2" active>Submenu Item</qtm-submenu-item>
      <qtm-submenu-item id="submenu3">Submenu Item</qtm-submenu-item>
    </qtm-submenu-item-list>
  </qtm-menu-item>
</qtm-menu-item-list>

active-id​

Set the active-id value to the active menu or submenu item ID by default.

<script>
  const items=[{label: "Menu item", id: "menu1", icon: "account_circle"},...]
  document.getElementById("menu-list").items = items
</script>

<qtm-menu-item-list id="menu-list" active-id="menu2"></qtm-menu-item-list>

disabled-ids​

Set the disabled-ids value to a list of ids of disabled menu items or disabled submenu items.

<script>
  const menu = document.getElementById("menu-list")
  const items=[{label: "Menu item", id: "menu1", icon: "account_circle"},...]
  menu.items = items
  const disabledIds=['menu1', 'submenu2']
  menu.disabledIds = disabledIds
</script>

<qtm-menu-item-list id="menu-list" active-id="menu2"></qtm-menu-item-list>

collapsed-ids​

Set the collapsed-ids value to a list of menu items that don't show their own nested submenu items by default.

<script>
  const menu = document.getElementById("menu-list")
  const items=[{label: "Menu item", id: "menu1", icon: "account_circle"},...]
  menu.items = items
  const collapsedIds = ['menu3']
  menu.collapsedIds = collapsedIds
</script>

<qtm-menu-item-list id="menu-list"></qtm-menu-item-list>

Scrolling​

scrollable​

If there are more menu items than can be displayed at once, you can make the menu item list scrollable by adding the scrollable attribute to this component. By default, the scrollable menu item list displays the first five menu items and half of the sixth one.

<script>
  const items=[{label: "Menu item", id: "menu1", icon: "account_circle"},...]
  document.getElementById("menu-list").items = items
</script>

<qtm-menu-item-list id="menu-list" scrollable></qtm-menu-item-list>

nb-visible-items​

If you want to change the number of visible items when the menu item list is scrollable, you can change value of the nb-visible-items prop.

<script>
  const items=[{label: "Menu item", id: "menu1", icon: "account_circle"},...]
  document.getElementById("menu-list").items = items
</script>

<qtm-menu-item-list id="menu-list" scrollable nb-visible-items="2"></qtm-menu-item-list>

Customization​

Add your own classes with the classes prop. This way you will be able to override or extend the styles applied to the component (you can use available utility classes by importing @qtm/css/dist/utilities.css).

<script>
  const items=[{label: "Menu item", id: "menu1", icon: "account_circle"},...]
  document.getElementById("menu-list").items = items
</script>

<qtm-menu-item-list id="menu-list" classes="bg-primary-100"></qtm-menu-item-list>

API​

Loading API documentation...
Loading API documentation...
Loading API documentation...
Loading API documentation...
Loading API documentation...

Spotted a bug, have a question, or want to suggest a new feature?

Submit an issue on GitLab