The ds-menu component can be used directly on page, or as part of ds-menubutton.

Options

Basic usage

Selected menu items

To highlight the currently selected menu item, either add the class ds-menu__item--selected or if you are using ARIA attributes you can use aria-selected="true".

Disabled menu items

Any button element with a disabled attribute, or any a element with href="" (empty value), href (with no value) or missing href will be displayed as disabled.

Dividers

Adjacent html ul elements will automatically be visually displayed with a divider.

Menu headers

Menu headers can be introduced by using ds-text components.

Sub menus

Collapsible sub menus can be displayed by using html <details> element

Width

Narrow, mid, wide

Height

By default the menu will be the height of the menu contents. You can also restrict the overall height of the menu and cause the contents to scroll. If the menu can scroll, a shadow will be added at the bottom/top of the menu to indicate the menu is scrollable.

You can apply these settings to either a ds-menubutton or to a standalone ds-menu component.

There are two ways to restrict the height.

Restrict the height to the viewport

Adding the class --viewport will restrict the height to 100vh - --ds-header-height (usually 100vh - 60px) and force the menu to scroll.

Restrict the height to a specific size

You can restrict the height by setting the --ds-menu-height or --ds-menu-max-height CSS var (either in a css file, inline style tag or via javascript).

• --ds-menu-height will force the menu to an exact size, white space will be included below the menu items if there are not enough items to fill the full menu
• --ds-menu-max-height will be as high as the list of menu items, but will limit the maximum height

let myCustomMenu = document.getElementById("customMenu");
myCustomMenu.style.setProperty("--ds-menu-height", "400px");

Menu icons

Icons can be applied to each menu item using ds-text--icon-*.

Menu descriptions

Descriptive text can be added to each menu item by including an html span element

Notification indicator

A menu item can display a notification indicator (dot) by adding the class __item --notification.

Additionally, if the menu item has an attribute data-notification-counter set to a non-empty value, that value will be shown in the indicator. If the attribute is set to empty data-notification-counter="" the indicator dot will be hidden.

Styles

Simple style

Dropdown style

Compact style

Table of Contents style

Accessibility

When used directly on page, this component is accessible. When used inside ds-menubutton, additional accessibility and keyboard support is required.

Role and ARIA attributes

See above

Keyboard access

When used directly on page this component can be selected using the browsers native tab and shift-tab keyboard command and enter to activate the selected item.

References

• Menubutton design pattern

Examples

Manifest

The component manifest describes this component's API — its modifiers, structure, data attributes, CSS custom properties, accessibility notes, and example markup. It is consumed by tooling such as AI assistants and code generators.

Latest version: https://assets.soracom.io/sds/latest/ds-menu/index.mjs