Menu — Smart UI JavaScript API

Menu — Smart UI JavaScript API

On this page + Quick start

Quick start · JavaScript

Complete starter source per framework. Run the scaffold/install command first, then replace the listed files with the full code below.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Menu - JavaScript Quick Start</title>
  <link rel="stylesheet" href="./node_modules/smart-webcomponents/source/styles/smart.default.css" />
</head>
<body>
  <smart-menu id="demo-menu"></smart-menu>

  <script type="module">
    import './node_modules/smart-webcomponents/source/modules/smart.menu.js';

    const el = document.getElementById('demo-menu');
    if (el) {

      el.mode = 'horizontal';
      el.selectionMode = 'click';
      el.dataSource = [
        { label: 'File', items: [{ label: 'New', shortcut: 'Ctrl+N' }, { label: 'Open', shortcut: 'Ctrl+O' }, { label: 'Save', shortcut: 'Ctrl+S' }] },
        { label: 'Edit', items: [{ label: 'Undo', shortcut: 'Ctrl+Z' }, { label: 'Redo', shortcut: 'Ctrl+Y' }] },
        { label: 'Help', items: [{ label: 'Docs' }, { label: 'About' }] }
      ];

      el.addEventListener('change', (event) => console.log('change:', event.detail || event));
    }
  </script>
</body>
</html>
For AI tooling

Developer Quick Reference

Component: Menu   Framework: JavaScript   Selector: smart-menu

API counts: 32 properties, 13 methods, 10 events

Common properties: 0, 1, 2, 3, 4, 5

Common methods: addItem(), checkItem(), clear(), clickItem(), close(), collapseItem()

Common events: close, closing, collapse, collapsing, expand, expanding

Module hint: smart-webcomponents/source/modules/smart.menu.js

Horizontal, Vertical and Popup Menu. Popup Menus appear when a user taps an interactive UI element such as an icon, button, action, or content, such as selected items or text.

Class

Menu
MenuItem
MenuItemsGroup

Menu

Horizontal, Vertical and Popup Menu. Popup Menus appear when a user taps an interactive UI element such as an icon, button, action, or content, such as selected items or text.

Selector

smart-menu

Quick picks

closedataSourcedisableditemsopen

Properties

AanimationSets or retrieves the current animation mode. When this property is set to 'none', all animations are disabled and the element remains static. Otherwise, animations will be enabled according to the specified mode.
AautoCloseDelaySpecifies the delay, in milliseconds, before the Menu dropdown is closed after the mouse cursor leaves the Menu area. This setting is only effective when the selectionMode property is set to 'mouseenter'. Adjusting this value can help prevent the dropdown from closing too quickly when the mouse briefly leaves the Menu.
AautoFocusOnMouseenterIf set to true, the element will automatically receive focus when the user's mouse pointer enters (hovers over) it, triggering a mouseenter event. This allows keyboard interactions or focus styles to activate without requiring a manual click or tab action from the user.
CcheckableEnables checkboxes for top-level menu items (the direct children of the main Menu component), allowing users to select or deselect these items. To make submenu items (nested within menu groups) checkable, set the checkable property individually on the corresponding smart-menu-items-group elements. This allows for granular control over which menu levels support checkable states.
CcheckboxesControls whether checkboxes and radio buttons can be shown within the Menu component. This property applies exclusively to the main Menu, not to its subitems (i.e., smart-menu-item or smart-menu-items-group). Use this property to enable or disable the display of selectable options directly in the Menu. For further customization of individual items, refer to the checkable property.
CcheckModeSets the selection mode (check mode) for the top-level Menu items, which are the immediate children of the Menu component. The 'checkMode' property determines how these menu items can be toggled or selected:- Possible values for 'checkMode' are: - ''checkbox'': Menu items can be checked and unchecked independently (multiple selections allowed). - ''radioButton'': Menu items are mutually exclusive (only one can be selected at a time, like radio buttons). - ''none'': Menu items have no checkable or selectable state.You can also assign a comma-separated list of these values (for example, ''checkbox, radioButton, none, checkbox''). If a list is provided, each value corresponds to a group of top-level menu items. These groups are separated by menu separators (special items acting as visual dividers). The first value in the list applies to the first group of menu items, the second value to the next group (after the first separator), and so on. When a separator is encountered, it signals the start of a new checkMode context, applying the next value in the list to subsequent items.Note: This 'checkMode' property only affects the top-level menu items. To control check modes for submenus or nested groups, set the 'checkMode' property individually on each smart-menu-items-group (the group component representing submenu levels).
CcloseActionDefines the document-level event that triggers the closure of all open menu dropdowns, or the entire menu if the mode property is set to 'dropDown'. This event ensures that any active menu or submenu is properly closed when the specified user interaction occurs (e.g., clicking outside the menu).
DdataSourceSpecifies the data source for the Menu component. The data source should be provided as an array of objects, where each object represents a menu item with the following properties:- 'label': *(string, required)* — The text displayed for the menu item.- 'value': *(any, required)* — The unique value associated with the menu item, used for identification or selection.- 'shortcut': *(string, optional)* — A keyboard shortcut hint displayed alongside the menu item, helping users discover quick access keys.- 'items': *(array, optional)* — An array of objects representing sub-menu items, allowing for nested menus and hierarchical structures. Each sub-menu item follows the same structure as a top-level menu item.By configuring the data source in this format, you enable dynamic and flexible rendering of complex menu structures.
DdisabledControls whether the element is active and interactive (enabled) or inactive and non-interactive (disabled). When disabled, users cannot interact with the element.
DdisplayMemberSpecifies which field in the data source should be used as the item's label. This determines the text value displayed for each item in the UI by mapping it to the corresponding property from your data.
DdropDownAnchorWhen this property is set and the Menu is in drop-down mode, the Menu's position will be anchored to the ID set by this property.
DdropDownAppendToHere is a revised and enhanced version of your description:Specifies a custom outer container to which all dropdown containers will be appended. By default, dropdown elements are appended inside the menu itself. You can assign this property an HTML element directly, or provide the id of an existing HTML element (as a string).When the menu is in mode 'dropDown', the dropDownAppendTo property not only determines where the dropdowns are appended, but also controls the parent container of the entire menu. Note that the open method will open the menu relative to its original position within the DOM, regardless of the value of dropDownAppendTo.Use this property to customize the DOM structure, for example, to ensure that dropdowns are rendered within a specific container for layout, styling, or layering purposes.
DdropDownOverlayWhen this property is enabled, opening an element’s dropdown will display a transparent overlay that covers the area between the dropdown and the rest of the page. This overlay prevents interaction with other page elements while the dropdown is open, helping to focus the user’s attention on the dropdown content.
DdropDownPositionSpecifies the direction in which the menu dropdown will appear when opened (e.g., above, below, left, or right relative to the triggering element), allowing customization of dropdown placement to enhance user interface layout and usability.
IitemsA getter method that retrieves and returns an array containing all current Menu item objects, allowing access to the complete list of menu entries managed by the application.
IitemsMemberSpecifies the field name in the data source that contains the collection of subitems associated with each item group. This property allows the component to identify and retrieve subitems for each group by referencing the appropriate data field.
LlocaleSpecifies or retrieves the current language setting for the component. This property determines which language is used when displaying text from the messages property, allowing for dynamic localization and internationalization of the user interface. When the language is changed, the corresponding localized messages are retrieved from the messages object.
LlocalizeFormatFunctionA callback function that allows you to customize the formatting of messages returned by the Localization Module. Use this to modify how localized strings are generated or displayed, such as adjusting placeholders, applying additional formatting, or handling special localization rules before the message is returned.
MmessagesSpecifies or retrieves an object containing the set of strings used within the widget interface that can be localized for different languages. This property works together with the locale property to enable internationalization by allowing developers to customize or translate UI text according to the user's language preferences.
MminimizeIconTemplateLoads a custom minimize icon from an HTMLTemplateElement selected by its ID. The element’s inner HTML is used as the icon’s template, allowing for flexible and reusable icon customization within the application.
MminimizeWidthSpecifies the minimum width (in pixels) at which the Menu transitions from its normal (expanded) state to a minimized (collapsed) mode. When the Menu’s container width falls below this threshold, the minimized mode is automatically activated. If set to null, the Menu will remain in its normal state regardless of width and will not minimize automatically.
MmodeSpecifies how the menu is visually presented to users, such as in a horizontal, vertical, dropdown, or collapsible format. Adjusting this setting allows customization of the menu’s layout and interaction style.
OopenedToggles the menu’s visibility when it is set to 'dropDown' mode, allowing users to open or close the menu as needed.
OoverflowDefines how the menu's scroll buttons behave when navigating through its items. This property is effective only if dropDownAppendTo is set to a value other than null. If dropDownAppendTo is null, the scroll button behavior setting is ignored.
PpreventCloseOnCheckIf set to true, the Menu and its dropdowns will remain open when a Menu item is checked or unchecked, rather than automatically closing upon selection. This allows users to make multiple selections without the Menu closing each time an item is toggled.
RreadonlyWhen the element is set to "readonly," users can view its content but are unable to modify or edit the value. However, users may still interact with the element in limited ways, such as selecting and copying its content. The element remains focusable, but any attempts to change its data will be ignored.
RrightToLeftSpecifies or retrieves whether the element’s alignment is configured to support locales that use right-to-left (RTL) text direction, such as Arabic or Hebrew. When enabled, the element’s content and layout are adjusted for proper display in RTL languages.
SselectionModeSpecifies how users can select items within the menu, such as allowing single selection, multiple selections, or no selection.
TthemeSpecifies the theme to be applied. The selected theme controls the visual appearance and styling of the element, including colors, fonts, spacing, and other design aspects.
UunfocusableWhen set to true, the element is removed from the tab order and cannot be focused using keyboard navigation or script.
UunlockKeyRetrieves or assigns the unlockKey, a unique code required to activate and access the product's full features.
VvalueMemberSpecifies which field in the data source should be used as the value for each item. This property maps a particular key or column from your data to represent the item's value in the component, enabling proper identification, selection, and data binding.

Events

CcloseThis event is triggered whenever the menu is closed by the user. It is only fired when the component is operating in 'dropDown' mode; other modes do not emit this event. Use this event to perform actions or cleanup tasks when the drop-down menu is dismissed.
CclosingThis event is dispatched immediately before the menu begins to close, providing an opportunity to intercept the closing operation. By invoking event.preventDefault() within the event handler, you can cancel the menu’s closure, allowing for custom logic or validation before the menu actually closes. Note that this event is only fired when the menu is operating in 'dropDown' mode; it does not apply to other display modes.
CcollapseThis event is triggered whenever a smart-menu-items-group is collapsed, indicating that a previously expanded group of menu items within the smartMenu component has been closed by the user or through a programmatic action. Use this event to perform custom actions or UI updates in response to the group collapsing.
CcollapsingThis event is triggered immediately before a smart-menu-items-group begins to collapse, allowing developers to execute custom logic or prevent the group from collapsing if necessary. It provides an opportunity to handle user interactions or update the user interface in response to the group collapsing action.
EexpandThis event is triggered whenever a smart-menu-items-group component is expanded by the user, either through a click or programmatic action. It allows you to execute custom logic in response to a menu group opening.
EexpandingThis event is fired immediately before a smart-menu-items-group begins to expand, allowing you to execute custom logic or cancel the expansion operation if needed. Use this event to intervene right before the menu group becomes visible to the user.
IitemCheckChangeThis event is triggered whenever the checked or unchecked state of a menu item is changed by the user or programmatically. It provides details about which menu item was affected and the new check state, allowing developers to respond to the change accordingly, such as updating the UI or processing the selected option.
IitemClickThis event is triggered whenever a user clicks on a menu item. It provides information about the selected menu item, allowing you to handle user interactions, perform actions based on the item selected, or update the interface accordingly.
OopenThis event is triggered whenever the menu is opened by the user. It is only fired when the component is operating in 'dropDown' mode; in all other modes, this event will not be triggered. Use this event to perform actions when the drop-down menu becomes visible.
OopeningThis event is triggered immediately before the menu is opened, giving you the opportunity to intervene before the menu becomes visible. Within your event handler, you can prevent the menu from opening by calling event.preventDefault(). Note that this event is only emitted when the menu is operating in 'dropDown' mode; it will not be fired in any other mode.

Methods

AaddItemAdds a new item to the menu by appending the specified entry, including its label, action, and any associated properties, to the existing menu structure. This allows dynamic expansion of the menu options displayed to users.
CcheckItemMarks the specified item as checked or selected, updating its status to indicate it is active, enabled, or chosen.
CclearRemoves all existing items from the Menu, resulting in an empty Menu with no selectable options.
CclickItemSimulates a user click event on a specified item programmatically, triggering any associated event handlers or actions as if the item were clicked manually by the user.
CcloseAutomatically closes the Menu when the mode property is set to 'dropDown', ensuring that the menu is dismissed upon selection or when clicking outside the menu area. This behavior provides a streamlined user experience consistent with standard dropdown functionality.
CcollapseItemCollapses a currently expanded item, hiding its content from view and displaying only the header or summary. This is typically used in expandable/collapsible components such as accordions or dropdown menus.
EexpandItemDisplays the detailed content or additional information of an item by expanding its view, typically used in accordions, dropdowns, or collapsible sections.
GgetItemRetrieves a specific item using either its unique identifier (ID) or a numeric path value. This allows you to access an item directly by providing its assigned ID or by specifying its position within a structured path.
MmaximizeExpands the menu to display all available options, maximizing its visibility and accessibility for the user.
MminimizeCollapses the navigation menu to its minimized or compact state, reducing its visible size to save screen space while still providing access to essential menu options.
OopenOpens the Menu component only when the mode property is set to 'dropDown'. In this mode, the Menu will become visible in a dropdown format, allowing users to interact with its items. If mode is set to any other value, the Menu will not open.
RremoveItemRemoves a specified item from the menu, updating the menu structure to reflect the change. This action ensures the targeted menu item is no longer displayed or accessible within the menu interface.
UuncheckItemUnselects or removes the checkmark from a selected item, indicating that it is no longer active, chosen, or included in the current selection.

Properties

animationSets or retrieves the current animation mode. When this property is set to 'none', all animations are disabled and the element remains static. Otherwise, animations will be enabled according to the specified mode."none" | "simple" | "advanced"

Sets or retrieves the current animation mode. When this property is set to 'none', all animations are disabled and the element remains static. Otherwise, animations will be enabled according to the specified mode.

Allowed Values

  • "none" - animation is disabled
  • "simple" - ripple animation is disabled
  • "advanced" - all animations are enabled

Default value

"advanced"

Examples

Markup and runtime examples for animation:

HTML:

<smart-menu animation="none"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.animation = "simple";

Read the current value:

const el = document.querySelector('smart-menu');
const animation = el.animation;

autoCloseDelaySpecifies the delay, in milliseconds, before the Menu dropdown is closed after the mouse cursor leaves the Menu area. This setting is only effective when the selectionMode property is set to 'mouseenter'. Adjusting this value can help prevent the dropdown from closing too quickly when the mouse briefly leaves the Menu.number

Specifies the delay, in milliseconds, before the Menu dropdown is closed after the mouse cursor leaves the Menu area. This setting is only effective when the selectionMode property is set to 'mouseenter'. Adjusting this value can help prevent the dropdown from closing too quickly when the mouse briefly leaves the Menu.

Default value

100
Try a demo showcasing the autoCloseDelay property.

Examples

Markup and runtime examples for autoCloseDelay:

HTML:

<smart-menu auto-close-delay="1000"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.autoCloseDelay = 200;

Read the current value:

const el = document.querySelector('smart-menu');
const autoCloseDelay = el.autoCloseDelay;

autoFocusOnMouseenterIf set to true, the element will automatically receive focus when the user's mouse pointer enters (hovers over) it, triggering a mouseenter event. This allows keyboard interactions or focus styles to activate without requiring a manual click or tab action from the user.boolean

If set to true, the element will automatically receive focus when the user's mouse pointer enters (hovers over) it, triggering a mouseenter event. This allows keyboard interactions or focus styles to activate without requiring a manual click or tab action from the user.

Default value

false

Examples

Markup and runtime examples for autoFocusOnMouseenter:

HTML attribute:

<smart-menu auto-focus-on-mouseenter></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.autoFocusOnMouseenter = false;

Read the current value:

const el = document.querySelector('smart-menu');
const autoFocusOnMouseenter = el.autoFocusOnMouseenter;

checkableEnables checkboxes for top-level menu items (the direct children of the main Menu component), allowing users to select or deselect these items. To make submenu items (nested within menu groups) checkable, set the checkable property individually on the corresponding smart-menu-items-group elements. This allows for granular control over which menu levels support checkable states.boolean

Enables checkboxes for top-level menu items (the direct children of the main Menu component), allowing users to select or deselect these items. To make submenu items (nested within menu groups) checkable, set the checkable property individually on the corresponding smart-menu-items-group elements. This allows for granular control over which menu levels support checkable states.

Default value

false
Try a demo showcasing the checkable property.

Examples

Markup and runtime examples for checkable:

HTML attribute:

<smart-menu checkable></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.checkable = false;

Read the current value:

const el = document.querySelector('smart-menu');
const checkable = el.checkable;

checkboxesControls whether checkboxes and radio buttons can be shown within the Menu component. This property applies exclusively to the main Menu, not to its subitems (i.e., smart-menu-item or smart-menu-items-group). Use this property to enable or disable the display of selectable options directly in the Menu. For further customization of individual items, refer to the checkable property.boolean

Controls whether checkboxes and radio buttons can be shown within the Menu component. This property applies exclusively to the main Menu, not to its subitems (i.e., smart-menu-item or smart-menu-items-group). Use this property to enable or disable the display of selectable options directly in the Menu.
For further customization of individual items, refer to the checkable property.

Default value

false
Try a demo showcasing the checkboxes property.

Examples

Markup and runtime examples for checkboxes:

HTML attribute:

<smart-menu checkboxes></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.checkboxes = false;

Read the current value:

const el = document.querySelector('smart-menu');
const checkboxes = el.checkboxes;

checkModeSets the selection mode (check mode) for the top-level Menu items, which are the immediate children of the Menu component. The 'checkMode' property determines how these menu items can be toggled or selected:- Possible values for 'checkMode' are: - ''checkbox'': Menu items can be checked and unchecked independently (multiple selections allowed). - ''radioButton'': Menu items are mutually exclusive (only one can be selected at a time, like radio buttons). - ''none'': Menu items have no checkable or selectable state.You can also assign a comma-separated list of these values (for example, ''checkbox, radioButton, none, checkbox''). If a list is provided, each value corresponds to a group of top-level menu items. These groups are separated by menu separators (special items acting as visual dividers). The first value in the list applies to the first group of menu items, the second value to the next group (after the first separator), and so on. When a separator is encountered, it signals the start of a new checkMode context, applying the next value in the list to subsequent items.Note: This 'checkMode' property only affects the top-level menu items. To control check modes for submenus or nested groups, set the 'checkMode' property individually on each smart-menu-items-group (the group component representing submenu levels)."checkbox" | "radioButton"

Sets the selection mode (check mode) for the top-level Menu items, which are the immediate children of the Menu component. The 'checkMode' property determines how these menu items can be toggled or selected:

- Possible values for 'checkMode' are:
- ''checkbox'': Menu items can be checked and unchecked independently (multiple selections allowed).
- ''radioButton'': Menu items are mutually exclusive (only one can be selected at a time, like radio buttons).
- ''none'': Menu items have no checkable or selectable state.

You can also assign a comma-separated list of these values (for example, ''checkbox, radioButton, none, checkbox''). If a list is provided, each value corresponds to a group of top-level menu items. These groups are separated by menu separators (special items acting as visual dividers). The first value in the list applies to the first group of menu items, the second value to the next group (after the first separator), and so on. When a separator is encountered, it signals the start of a new checkMode context, applying the next value in the list to subsequent items.

Note: This 'checkMode' property only affects the top-level menu items. To control check modes for submenus or nested groups, set the 'checkMode' property individually on each smart-menu-items-group (the group component representing submenu levels).

Allowed Values

  • "checkbox" - A check box is shown inside a menu item that is selected.
  • "radioButton" - A radio dot is shown inside a menu item that is selected.

Default value

"checkbox"
Try a demo showcasing the checkMode property.

Examples

Markup and runtime examples for checkMode:

HTML:

<smart-menu check-mode="radioButton"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.checkMode = "checkbox";

Read the current value:

const el = document.querySelector('smart-menu');
const checkMode = el.checkMode;

closeActionDefines the document-level event that triggers the closure of all open menu dropdowns, or the entire menu if the mode property is set to 'dropDown'. This event ensures that any active menu or submenu is properly closed when the specified user interaction occurs (e.g., clicking outside the menu)."down" | "up" | "none"

Defines the document-level event that triggers the closure of all open menu dropdowns, or the entire menu if the mode property is set to 'dropDown'. This event ensures that any active menu or submenu is properly closed when the specified user interaction occurs (e.g., clicking outside the menu).

Allowed Values

  • "down" - Closes the drop down on document down event.
  • "up" - Closes the drop down on document up event.
  • "none" - The drop down can be closed only from the menu.

Default value

"up"

Examples

Markup and runtime examples for closeAction:

HTML:

<smart-menu close-action="down"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.closeAction = "none";

Read the current value:

const el = document.querySelector('smart-menu');
const closeAction = el.closeAction;

dataSourceSpecifies the data source for the Menu component. The data source should be provided as an array of objects, where each object represents a menu item with the following properties:- 'label': *(string, required)* — The text displayed for the menu item.- 'value': *(any, required)* — The unique value associated with the menu item, used for identification or selection.- 'shortcut': *(string, optional)* — A keyboard shortcut hint displayed alongside the menu item, helping users discover quick access keys.- 'items': *(array, optional)* — An array of objects representing sub-menu items, allowing for nested menus and hierarchical structures. Each sub-menu item follows the same structure as a top-level menu item.By configuring the data source in this format, you enable dynamic and flexible rendering of complex menu structures.{label: string, shortcut: string, value: any, items:[]}[]

Specifies the data source for the Menu component. The data source should be provided as an array of objects, where each object represents a menu item with the following properties:

- 'label': *(string, required)* — The text displayed for the menu item.
- 'value': *(any, required)* — The unique value associated with the menu item, used for identification or selection.
- 'shortcut': *(string, optional)* — A keyboard shortcut hint displayed alongside the menu item, helping users discover quick access keys.
- 'items': *(array, optional)* — An array of objects representing sub-menu items, allowing for nested menus and hierarchical structures. Each sub-menu item follows the same structure as a top-level menu item.

By configuring the data source in this format, you enable dynamic and flexible rendering of complex menu structures.

Try a demo showcasing the dataSource property.

Examples

Markup and runtime examples for dataSource:

HTML:

<smart-menu data-source="[{ label: "File" }, { label: "Help" }]"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.dataSource = [{ label: 'File', items: [{ label: 'New', shortcut: 'Ctrl+N' }] }];

Read the current value:

const el = document.querySelector('smart-menu');
const dataSource = el.dataSource;

disabledControls whether the element is active and interactive (enabled) or inactive and non-interactive (disabled). When disabled, users cannot interact with the element.boolean

Controls whether the element is active and interactive (enabled) or inactive and non-interactive (disabled). When disabled, users cannot interact with the element.

Default value

false
Try a demo showcasing the disabled property.

Examples

Markup and runtime examples for disabled:

HTML attribute:

<smart-menu disabled></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.disabled = false;

Read the current value:

const el = document.querySelector('smart-menu');
const disabled = el.disabled;

displayMemberSpecifies which field in the data source should be used as the item's label. This determines the text value displayed for each item in the UI by mapping it to the corresponding property from your data.string

Specifies which field in the data source should be used as the item's label. This determines the text value displayed for each item in the UI by mapping it to the corresponding property from your data.

Default value

"label"

Examples

Markup and runtime examples for displayMember:

HTML:

<smart-menu display-member="title"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.displayMember = "caption";

Read the current value:

const el = document.querySelector('smart-menu');
const displayMember = el.displayMember;

dropDownAnchorWhen this property is set and the Menu is in drop-down mode, the Menu's position will be anchored to the ID set by this property.string

When this property is set and the Menu is in drop-down mode, the Menu's position will be anchored to the ID set by this property.

Default value

""

Examples

Markup and runtime examples for dropDownAnchor:

HTML:

<smart-menu drop-down-anchor="#button"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.dropDownAnchor = "#otherButton";

Read the current value:

const el = document.querySelector('smart-menu');
const dropDownAnchor = el.dropDownAnchor;

dropDownAppendToHere is a revised and enhanced version of your description:Specifies a custom outer container to which all dropdown containers will be appended. By default, dropdown elements are appended inside the menu itself. You can assign this property an HTML element directly, or provide the id of an existing HTML element (as a string).When the menu is in mode 'dropDown', the dropDownAppendTo property not only determines where the dropdowns are appended, but also controls the parent container of the entire menu. Note that the open method will open the menu relative to its original position within the DOM, regardless of the value of dropDownAppendTo.Use this property to customize the DOM structure, for example, to ensure that dropdowns are rendered within a specific container for layout, styling, or layering purposes.string | HTMLElement

Here is a revised and enhanced version of your description:

Specifies a custom outer container to which all dropdown containers will be appended. By default, dropdown elements are appended inside the menu itself. You can assign this property an HTML element directly, or provide the id of an existing HTML element (as a string).

When the menu is in mode 'dropDown', the dropDownAppendTo property not only determines where the dropdowns are appended, but also controls the parent container of the entire menu. Note that the open method will open the menu relative to its original position within the DOM, regardless of the value of dropDownAppendTo.

Use this property to customize the DOM structure, for example, to ensure that dropdowns are rendered within a specific container for layout, styling, or layering purposes.

Try a demo showcasing the dropDownAppendTo property.

Examples

Markup and runtime examples for dropDownAppendTo:

HTML:

<smart-menu drop-down-append-to="body"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.dropDownAppendTo = "'customContainer'";

Read the current value:

const el = document.querySelector('smart-menu');
const dropDownAppendTo = el.dropDownAppendTo;

dropDownOverlayWhen this property is enabled, opening an element’s dropdown will display a transparent overlay that covers the area between the dropdown and the rest of the page. This overlay prevents interaction with other page elements while the dropdown is open, helping to focus the user’s attention on the dropdown content.boolean

When this property is enabled, opening an element’s dropdown will display a transparent overlay that covers the area between the dropdown and the rest of the page. This overlay prevents interaction with other page elements while the dropdown is open, helping to focus the user’s attention on the dropdown content.

Default value

false

Examples

Markup and runtime examples for dropDownOverlay:

HTML attribute:

<smart-menu drop-down-overlay></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.dropDownOverlay = false;

Read the current value:

const el = document.querySelector('smart-menu');
const dropDownOverlay = el.dropDownOverlay;

dropDownPositionSpecifies the direction in which the menu dropdown will appear when opened (e.g., above, below, left, or right relative to the triggering element), allowing customization of dropdown placement to enhance user interface layout and usability."auto" | "top-left" | "top-right" | "bottom-left" | "bottom-right" | "overlay-left" | "overlay-right"

Specifies the direction in which the menu dropdown will appear when opened (e.g., above, below, left, or right relative to the triggering element), allowing customization of dropdown placement to enhance user interface layout and usability.

Allowed Values

  • "auto" - The position is automatically determined by measuring the available distance around the element for the drop down to open freely without being clipped by the edges of the browser. By default the drop down will try to open below the element. If the available space is not enough for the popup to appear it will open in one of the following directions, if possible: top, over.
  • "top-left" - The drop down opens above and to the left of the seleted Item Group.
  • "top-right" - The drop down opens above and to the right of the seleted Item Group.
  • "bottom-left" - The drop down opens below and to the left of the seleted Item Group.
  • "bottom-right" - The drop down opens below and to the right of the seleted Item Group.
  • "overlay-left" - The drop down opens over the seleted Item Group by aligning to the left.
  • "overlay-right" - The drop down opens over and to the left of the seleted Item Group by aligning to the right.

Default value

"auto"
Try a demo showcasing the dropDownPosition property.

Examples

Markup and runtime examples for dropDownPosition:

HTML:

<smart-menu drop-down-position="top-left"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.dropDownPosition = "top-right";

Read the current value:

const el = document.querySelector('smart-menu');
const dropDownPosition = el.dropDownPosition;

itemsA getter method that retrieves and returns an array containing all current Menu item objects, allowing access to the complete list of menu entries managed by the application.array

A getter method that retrieves and returns an array containing all current Menu item objects, allowing access to the complete list of menu entries managed by the application.

Default value

Try a demo showcasing the items property.

itemsMemberSpecifies the field name in the data source that contains the collection of subitems associated with each item group. This property allows the component to identify and retrieve subitems for each group by referencing the appropriate data field.string

Specifies the field name in the data source that contains the collection of subitems associated with each item group. This property allows the component to identify and retrieve subitems for each group by referencing the appropriate data field.

Default value

"items"

Examples

Markup and runtime examples for itemsMember:

HTML:

<smart-menu items-member="children"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.itemsMember = "subitems";

Read the current value:

const el = document.querySelector('smart-menu');
const itemsMember = el.itemsMember;

localeSpecifies or retrieves the current language setting for the component. This property determines which language is used when displaying text from the messages property, allowing for dynamic localization and internationalization of the user interface. When the language is changed, the corresponding localized messages are retrieved from the messages object.string

Specifies or retrieves the current language setting for the component. This property determines which language is used when displaying text from the messages property, allowing for dynamic localization and internationalization of the user interface. When the language is changed, the corresponding localized messages are retrieved from the messages object.

Default value

"en"

Examples

Markup and runtime examples for locale:

HTML:

<smart-menu locale="de"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.locale = "en";

Read the current value:

const el = document.querySelector('smart-menu');
const locale = el.locale;

localizeFormatFunctionA callback function that allows you to customize the formatting of messages returned by the Localization Module. Use this to modify how localized strings are generated or displayed, such as adjusting placeholders, applying additional formatting, or handling special localization rules before the message is returned.function | null

A callback function that allows you to customize the formatting of messages returned by the Localization Module. Use this to modify how localized strings are generated or displayed, such as adjusting placeholders, applying additional formatting, or handling special localization rules before the message is returned.

Examples

Markup and runtime examples for localizeFormatFunction:

HTML:

<smart-menu localize-format-function="function(defaultMessage, message, messageArguments){return '...'}"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.localizeFormatFunction = "function(defaultMessage, message, messageArguments){return '...'}";

Read the current value:

const el = document.querySelector('smart-menu');
const localizeFormatFunction = el.localizeFormatFunction;

messagesSpecifies or retrieves an object containing the set of strings used within the widget interface that can be localized for different languages. This property works together with the locale property to enable internationalization by allowing developers to customize or translate UI text according to the user's language preferences.object

Specifies or retrieves an object containing the set of strings used within the widget interface that can be localized for different languages. This property works together with the locale property to enable internationalization by allowing developers to customize or translate UI text according to the user's language preferences.

Default value




"en": {

"propertyUnknownType": "'{{name}}' property is with undefined 'type' member!",

"propertyInvalidValue": "Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!",

"propertyInvalidValueType": "Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!",

"elementNotInDOM": "Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.",

"moduleUndefined": "Module is undefined.",

"missingReference": "{{elementType}}: Missing reference to {{files}}.",

"htmlTemplateNotSuported": "{{elementType}}: Browser doesn't support HTMLTemplate elements.",

"invalidTemplate": "{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."

}

Examples

Markup and runtime examples for messages:

HTML:

<smart-menu messages="{"de":{"propertyUnknownType":"'{{name}}' Eigenschaft ist mit undefined 'Typ'-Member!","propertyInvalidValue":"Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!","propertyInvalidValueType":"Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!","elementNotInDOM":"Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.","moduleUndefined":"Modul ist nicht definiert.","missingReference":"{{elementType}}: Fehlender Verweis auf {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Browser unterstutzt keine HTMLTemplate-Elemente.","invalidTemplate":"{{elementType}}: '{{property}}' Die Eigenschaft akzeptiert eine Zeichenfolge, die mit der ID eines HTMLTemplate-Elements aus dem DOM ubereinstimmen muss."}}"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.messages = {"en":{"propertyUnknownType":"'{{name}}' property is with undefined 'type' member!","propertyInvalidValue":"Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!","propertyInvalidValueType":"Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!","elementNotInDOM":"Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.","moduleUndefined":"Module is undefined.","missingReference":"{{elementType}}: Missing reference to {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Browser doesn't support HTMLTemplate elements.","invalidTemplate":"{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM."}};

Read the current value:

const el = document.querySelector('smart-menu');
const messages = el.messages;

minimizeIconTemplateLoads a custom minimize icon from an HTMLTemplateElement selected by its ID. The element’s inner HTML is used as the icon’s template, allowing for flexible and reusable icon customization within the application.string

Loads a custom minimize icon from an HTMLTemplateElement selected by its ID. The element’s inner HTML is used as the icon’s template, allowing for flexible and reusable icon customization within the application.

Default value

"null"
Try a demo showcasing the minimizeIconTemplate property.

Examples

Markup and runtime examples for minimizeIconTemplate:

HTML:

<smart-menu minimize-icon-template="template1"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.minimizeIconTemplate = "template2";

Read the current value:

const el = document.querySelector('smart-menu');
const minimizeIconTemplate = el.minimizeIconTemplate;

minimizeWidthSpecifies the minimum width (in pixels) at which the Menu transitions from its normal (expanded) state to a minimized (collapsed) mode. When the Menu’s container width falls below this threshold, the minimized mode is automatically activated. If set to null, the Menu will remain in its normal state regardless of width and will not minimize automatically.number

Specifies the minimum width (in pixels) at which the Menu transitions from its normal (expanded) state to a minimized (collapsed) mode. When the Menu’s container width falls below this threshold, the minimized mode is automatically activated. If set to null, the Menu will remain in its normal state regardless of width and will not minimize automatically.

Examples

Markup and runtime examples for minimizeWidth:

HTML:

<smart-menu minimize-width="100"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.minimizeWidth = 200;

Read the current value:

const el = document.querySelector('smart-menu');
const minimizeWidth = el.minimizeWidth;

modeSpecifies how the menu is visually presented to users, such as in a horizontal, vertical, dropdown, or collapsible format. Adjusting this setting allows customization of the menu’s layout and interaction style."horizontal" | "vertical" | "dropDown" | "tree"

Specifies how the menu is visually presented to users, such as in a horizontal, vertical, dropdown, or collapsible format. Adjusting this setting allows customization of the menu’s layout and interaction style.

Allowed Values

  • "horizontal" - Menu root items are displayed horizontally and the drop down appears below/above or over the element.
  • "vertical" - Menu root items are displayed vertically and the drop down appears to the left/right or over the element.
  • "dropDown" - The menu acts as a popup. It's hidden by default. Calling the open and close methods can show or hide it.
  • "tree" - The menu appears as a tree and all items are aligned according to their parents.

Default value

"horizontal"
Try a demo showcasing the mode property.

Examples

Markup and runtime examples for mode:

HTML:

<smart-menu mode="vertical"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.mode = "dropDown";

Read the current value:

const el = document.querySelector('smart-menu');
const mode = el.mode;

openedToggles the menu’s visibility when it is set to 'dropDown' mode, allowing users to open or close the menu as needed.boolean

Toggles the menu’s visibility when it is set to 'dropDown' mode, allowing users to open or close the menu as needed.

Default value

false

Examples

Markup and runtime examples for opened:

HTML attribute:

<smart-menu opened></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.opened = false;

Read the current value:

const el = document.querySelector('smart-menu');
const opened = el.opened;

overflowDefines how the menu's scroll buttons behave when navigating through its items. This property is effective only if dropDownAppendTo is set to a value other than null. If dropDownAppendTo is null, the scroll button behavior setting is ignored."auto" | "hidden" | "scroll"

Defines how the menu's scroll buttons behave when navigating through its items. This property is effective only if dropDownAppendTo is set to a value other than null. If dropDownAppendTo is null, the scroll button behavior setting is ignored.

Allowed Values

  • "auto" - The scroll buttons are automatically shown/hidden depending on the visibility of the items. If there's an item that is not visible the appropriate scroll button will appear in order to fully scroll to it.
  • "hidden" - The scroll buttons are hidden.
  • "scroll" - The scroll buttons are always visible.

Default value

"auto"
Try a demo showcasing the overflow property.

Examples

Markup and runtime examples for overflow:

HTML:

<smart-menu overflow="hidden"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.overflow = "scroll";

Read the current value:

const el = document.querySelector('smart-menu');
const overflow = el.overflow;

preventCloseOnCheckIf set to true, the Menu and its dropdowns will remain open when a Menu item is checked or unchecked, rather than automatically closing upon selection. This allows users to make multiple selections without the Menu closing each time an item is toggled.boolean

If set to true, the Menu and its dropdowns will remain open when a Menu item is checked or unchecked, rather than automatically closing upon selection. This allows users to make multiple selections without the Menu closing each time an item is toggled.

Default value

false
Try a demo showcasing the preventCloseOnCheck property.

Examples

Markup and runtime examples for preventCloseOnCheck:

HTML attribute:

<smart-menu prevent-close-on-check></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.preventCloseOnCheck = false;

Read the current value:

const el = document.querySelector('smart-menu');
const preventCloseOnCheck = el.preventCloseOnCheck;

readonlyWhen the element is set to "readonly," users can view its content but are unable to modify or edit the value. However, users may still interact with the element in limited ways, such as selecting and copying its content. The element remains focusable, but any attempts to change its data will be ignored.boolean

When the element is set to "readonly," users can view its content but are unable to modify or edit the value. However, users may still interact with the element in limited ways, such as selecting and copying its content. The element remains focusable, but any attempts to change its data will be ignored.

Default value

false
Try a demo showcasing the readonly property.

Examples

Markup and runtime examples for readonly:

HTML attribute:

<smart-menu readonly></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.readonly = true;

Read the current value:

const el = document.querySelector('smart-menu');
const readonly = el.readonly;

rightToLeftSpecifies or retrieves whether the element’s alignment is configured to support locales that use right-to-left (RTL) text direction, such as Arabic or Hebrew. When enabled, the element’s content and layout are adjusted for proper display in RTL languages.boolean

Specifies or retrieves whether the element’s alignment is configured to support locales that use right-to-left (RTL) text direction, such as Arabic or Hebrew. When enabled, the element’s content and layout are adjusted for proper display in RTL languages.

Default value

false
Try a demo showcasing the rightToLeft property.

Examples

Markup and runtime examples for rightToLeft:

HTML attribute:

<smart-menu right-to-left></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.rightToLeft = false;

Read the current value:

const el = document.querySelector('smart-menu');
const rightToLeft = el.rightToLeft;

selectionModeSpecifies how users can select items within the menu, such as allowing single selection, multiple selections, or no selection."click" | "mouseenter"

Specifies how users can select items within the menu, such as allowing single selection, multiple selections, or no selection.

Allowed Values

  • "click" - A menu item is selected when clicked.
  • "mouseenter" - A menu item is selected when hovered

Default value

"click"
Try a demo showcasing the selectionMode property.

Examples

Markup and runtime examples for selectionMode:

HTML:

<smart-menu selection-mode="mouseenter"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.selectionMode = "click";

Read the current value:

const el = document.querySelector('smart-menu');
const selectionMode = el.selectionMode;

themeSpecifies the theme to be applied. The selected theme controls the visual appearance and styling of the element, including colors, fonts, spacing, and other design aspects.string

Specifies the theme to be applied. The selected theme controls the visual appearance and styling of the element, including colors, fonts, spacing, and other design aspects.

Default value

""
Try a demo showcasing the theme property.

Examples

Markup and runtime examples for theme:

HTML:

<smart-menu theme="blue"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.theme = "red";

Read the current value:

const el = document.querySelector('smart-menu');
const theme = el.theme;

unfocusableWhen set to true, the element is removed from the tab order and cannot be focused using keyboard navigation or script.boolean

When set to true, the element is removed from the tab order and cannot be focused using keyboard navigation or script.

Default value

false

Examples

Markup and runtime examples for unfocusable:

HTML attribute:

<smart-menu unfocusable></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.unfocusable = false;

Read the current value:

const el = document.querySelector('smart-menu');
const unfocusable = el.unfocusable;

unlockKeyRetrieves or assigns the unlockKey, a unique code required to activate and access the product's full features.string

Retrieves or assigns the unlockKey, a unique code required to activate and access the product's full features.

Default value

""

Examples

Markup and runtime examples for unlockKey:

HTML:

<smart-menu unlock-key=""></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.unlockKey = "1111-2222-3333-4444-5555";

Read the current value:

const el = document.querySelector('smart-menu');
const unlockKey = el.unlockKey;

valueMemberSpecifies which field in the data source should be used as the value for each item. This property maps a particular key or column from your data to represent the item's value in the component, enabling proper identification, selection, and data binding.string

Specifies which field in the data source should be used as the value for each item. This property maps a particular key or column from your data to represent the item's value in the component, enabling proper identification, selection, and data binding.

Default value

"value"
Try a demo showcasing the valueMember property.

Examples

Markup and runtime examples for valueMember:

HTML:

<smart-menu value-member="info"></smart-menu>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu');
el.valueMember = "details";

Read the current value:

const el = document.querySelector('smart-menu');
const valueMember = el.valueMember;

Events

closeThis event is triggered whenever the menu is closed by the user. It is only fired when the component is operating in 'dropDown' mode; other modes do not emit this event. Use this event to perform actions or cleanup tasks when the drop-down menu is dismissed.CustomEvent

This event is triggered whenever the menu is closed by the user. It is only fired when the component is operating in 'dropDown' mode; other modes do not emit this event. Use this event to perform actions or cleanup tasks when the drop-down menu is dismissed.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onClose

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Examples

Listen for close using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-menu')?.addEventListener('close', (event) => {
	// event handling code goes here.
})

closingThis event is dispatched immediately before the menu begins to close, providing an opportunity to intercept the closing operation. By invoking event.preventDefault() within the event handler, you can cancel the menu’s closure, allowing for custom logic or validation before the menu actually closes. Note that this event is only fired when the menu is operating in 'dropDown' mode; it does not apply to other display modes.CustomEvent

This event is dispatched immediately before the menu begins to close, providing an opportunity to intercept the closing operation. By invoking event.preventDefault() within the event handler, you can cancel the menu’s closure, allowing for custom logic or validation before the menu actually closes. Note that this event is only fired when the menu is operating in 'dropDown' mode; it does not apply to other display modes.

  • Bubbles Yes
  • Cancelable Yes
  • Interface CustomEvent
  • Event handler property onClosing

Arguments

evCustomEvent
ev.detailObject
ev.detail.trigger - Indicates whether the event was called from inside the element or programatically.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Examples

Listen for closing using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-menu')?.addEventListener('closing', (event) => {
    const detail = event.detail,
        trigger = detail.trigger;

	// event handling code goes here.
})

collapseThis event is triggered whenever a smart-menu-items-group is collapsed, indicating that a previously expanded group of menu items within the smartMenu component has been closed by the user or through a programmatic action. Use this event to perform custom actions or UI updates in response to the group collapsing.CustomEvent

This event is triggered whenever a smart-menu-items-group is collapsed, indicating that a previously expanded group of menu items within the smartMenu component has been closed by the user or through a programmatic action. Use this event to perform custom actions or UI updates in response to the group collapsing.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onCollapse

Arguments

evCustomEvent
ev.detailObject
ev.detail.item - The menu item that was collapsed.
ev.detail.label - The label of the toggled item that was collapsed.
ev.detail.value - The value of the toggled item that was collapsed.
ev.detail.path - The path of the toggled item that was collapsed, e.g. '0.1', '1.1.2'.
ev.detail.children - The children items of the toggled item that was collapsed.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Examples

Listen for collapse using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-menu')?.addEventListener('collapse', (event) => {
    const detail = event.detail,
        item = detail.item,
        label = detail.label,
        value = detail.value,
        path = detail.path,
        children = detail.children;

	// event handling code goes here.
})

collapsingThis event is triggered immediately before a smart-menu-items-group begins to collapse, allowing developers to execute custom logic or prevent the group from collapsing if necessary. It provides an opportunity to handle user interactions or update the user interface in response to the group collapsing action.CustomEvent

This event is triggered immediately before a smart-menu-items-group begins to collapse, allowing developers to execute custom logic or prevent the group from collapsing if necessary. It provides an opportunity to handle user interactions or update the user interface in response to the group collapsing action.

  • Bubbles Yes
  • Cancelable Yes
  • Interface CustomEvent
  • Event handler property onCollapsing

Arguments

evCustomEvent
ev.detailObject
ev.detail.item - The menu item that is going to be collapsed.
ev.detail.label - The label of the toggled item that is going to be collapsed.
ev.detail.value - The value of the toggled item that is going to be collapsed.
ev.detail.path - The path of the toggled item that is going to be collapsed, e.g. '0.1', '1.1.2'.
ev.detail.children - The children items of the toggled item that is going to be collapsed.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Examples

Listen for collapsing using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-menu')?.addEventListener('collapsing', (event) => {
    const detail = event.detail,
        item = detail.item,
        label = detail.label,
        value = detail.value,
        path = detail.path,
        children = detail.children;

	// event handling code goes here.
})

expandThis event is triggered whenever a smart-menu-items-group component is expanded by the user, either through a click or programmatic action. It allows you to execute custom logic in response to a menu group opening.CustomEvent

This event is triggered whenever a smart-menu-items-group component is expanded by the user, either through a click or programmatic action. It allows you to execute custom logic in response to a menu group opening.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onExpand

Arguments

evCustomEvent
ev.detailObject
ev.detail.item - The menu item that was expanded.
ev.detail.label - The label of the toggled item that was expanded.
ev.detail.value - The value of the toggled item that was expanded.
ev.detail.path - The path of the toggled item that was expanded, e.g. '0.1', '1.1.2'.
ev.detail.children - The children items of the toggled item that was expanded.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Examples

Listen for expand using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-menu')?.addEventListener('expand', (event) => {
    const detail = event.detail,
        item = detail.item,
        label = detail.label,
        value = detail.value,
        path = detail.path,
        children = detail.children;

	// event handling code goes here.
})

expandingThis event is fired immediately before a smart-menu-items-group begins to expand, allowing you to execute custom logic or cancel the expansion operation if needed. Use this event to intervene right before the menu group becomes visible to the user.CustomEvent

This event is fired immediately before a smart-menu-items-group begins to expand, allowing you to execute custom logic or cancel the expansion operation if needed. Use this event to intervene right before the menu group becomes visible to the user.

  • Bubbles Yes
  • Cancelable Yes
  • Interface CustomEvent
  • Event handler property onExpanding

Arguments

evCustomEvent
ev.detailObject
ev.detail.item - The menu item that is going to be expanded.
ev.detail.label - The label of the toggled item that is going to be expanded.
ev.detail.value - The value of the toggled item that is going to be expanded.
ev.detail.path - The path of the toggled item that is going to be expanded, e.g. '0.1', '1.1.2'.
ev.detail.children - The children items of the toggled item that is going to be expanded.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Examples

Listen for expanding using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-menu')?.addEventListener('expanding', (event) => {
    const detail = event.detail,
        item = detail.item,
        label = detail.label,
        value = detail.value,
        path = detail.path,
        children = detail.children;

	// event handling code goes here.
})

itemCheckChangeThis event is triggered whenever the checked or unchecked state of a menu item is changed by the user or programmatically. It provides details about which menu item was affected and the new check state, allowing developers to respond to the change accordingly, such as updating the UI or processing the selected option.CustomEvent

This event is triggered whenever the checked or unchecked state of a menu item is changed by the user or programmatically. It provides details about which menu item was affected and the new check state, allowing developers to respond to the change accordingly, such as updating the UI or processing the selected option.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onItemCheckChange

Arguments

evCustomEvent
ev.detailObject
ev.detail.item - The menu item which state was changed.
ev.detail.label - The label of the item which state was changed.
ev.detail.value - The value of the item which state was changed.
ev.detail.checked - The checked state of the toggled item. If false the item is not toggled.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the itemCheckChange event.

Examples

Listen for itemCheckChange using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-menu')?.addEventListener('itemCheckChange', (event) => {
    const detail = event.detail,
        item = detail.item,
        label = detail.label,
        value = detail.value,
        checked = detail.checked;

	// event handling code goes here.
})

itemClickThis event is triggered whenever a user clicks on a menu item. It provides information about the selected menu item, allowing you to handle user interactions, perform actions based on the item selected, or update the interface accordingly.CustomEvent

This event is triggered whenever a user clicks on a menu item. It provides information about the selected menu item, allowing you to handle user interactions, perform actions based on the item selected, or update the interface accordingly.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onItemClick

Arguments

evCustomEvent
ev.detailObject
ev.detail.item - The menu item that is toggled.
ev.detail.label - The label of the toggled item.
ev.detail.value - The value of the toggled item.

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the itemClick event.

Examples

Listen for itemClick using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-menu')?.addEventListener('itemClick', (event) => {
    const detail = event.detail,
        item = detail.item,
        label = detail.label,
        value = detail.value;

	// event handling code goes here.
})

openThis event is triggered whenever the menu is opened by the user. It is only fired when the component is operating in 'dropDown' mode; in all other modes, this event will not be triggered. Use this event to perform actions when the drop-down menu becomes visible.CustomEvent

This event is triggered whenever the menu is opened by the user. It is only fired when the component is operating in 'dropDown' mode; in all other modes, this event will not be triggered. Use this event to perform actions when the drop-down menu becomes visible.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onOpen

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Examples

Listen for open using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-menu')?.addEventListener('open', (event) => {
	// event handling code goes here.
})

openingThis event is triggered immediately before the menu is opened, giving you the opportunity to intervene before the menu becomes visible. Within your event handler, you can prevent the menu from opening by calling event.preventDefault(). Note that this event is only emitted when the menu is operating in 'dropDown' mode; it will not be fired in any other mode.CustomEvent

This event is triggered immediately before the menu is opened, giving you the opportunity to intervene before the menu becomes visible. Within your event handler, you can prevent the menu from opening by calling event.preventDefault(). Note that this event is only emitted when the menu is operating in 'dropDown' mode; it will not be fired in any other mode.

  • Bubbles Yes
  • Cancelable Yes
  • Interface CustomEvent
  • Event handler property onOpening

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Examples

Listen for opening using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-menu')?.addEventListener('opening', (event) => {
	// event handling code goes here.
})

Methods

addItem( Item: HTMLElement, Parent?: HTMLElement | string): voidAdds a new item to the menu by appending the specified entry, including its label, action, and any associated properties, to the existing menu structure. This allows dynamic expansion of the menu options displayed to users.

Adds a new item to the menu by appending the specified entry, including its label, action, and any associated properties, to the existing menu structure. This allows dynamic expansion of the menu options displayed to users.

Arguments

ItemHTMLElement

A smart-menu-item to add to the Menu.

Parent?HTMLElement | string

The smart-menu-items-group or its id or numeric path to add the item to.

On the custom element in the DOM (narrow the selector, e.g. to #my-menu, if you host multiple widgets):

document.querySelector('smart-menu')?.addItem("document.createElement('smart-menu-item')","0");

Try a demo showcasing the addItem method.

checkItem( item: HTMLElement | string): voidMarks the specified item as checked or selected, updating its status to indicate it is active, enabled, or chosen.

Marks the specified item as checked or selected, updating its status to indicate it is active, enabled, or chosen.

Arguments

itemHTMLElement | string

smart-menu-item/smart-menu-items-group or its id or numeric path.

On the custom element in the DOM (narrow the selector, e.g. to #my-menu, if you host multiple widgets):

document.querySelector('smart-menu')?.checkItem("0.0");

Try a demo showcasing the checkItem method.

clear(): voidRemoves all existing items from the Menu, resulting in an empty Menu with no selectable options.

Removes all existing items from the Menu, resulting in an empty Menu with no selectable options.

On the custom element in the DOM (narrow the selector, e.g. to #my-menu, if you host multiple widgets):

document.querySelector('smart-menu')?.clear();

Try a demo showcasing the clear method.

clickItem( item: HTMLElement | string): voidSimulates a user click event on a specified item programmatically, triggering any associated event handlers or actions as if the item were clicked manually by the user.

Simulates a user click event on a specified item programmatically, triggering any associated event handlers or actions as if the item were clicked manually by the user.

Arguments

itemHTMLElement | string

smart-menu-item/smart-menu-items-group or its id or numeric path.

On the custom element in the DOM (narrow the selector, e.g. to #my-menu, if you host multiple widgets):

document.querySelector('smart-menu')?.clickItem("menuItemRef");

close(): voidAutomatically closes the Menu when the mode property is set to 'dropDown', ensuring that the menu is dismissed upon selection or when clicking outside the menu area. This behavior provides a streamlined user experience consistent with standard dropdown functionality.

Automatically closes the Menu when the mode property is set to 'dropDown', ensuring that the menu is dismissed upon selection or when clicking outside the menu area. This behavior provides a streamlined user experience consistent with standard dropdown functionality.

On the custom element in the DOM (narrow the selector, e.g. to #my-menu, if you host multiple widgets):

document.querySelector('smart-menu')?.close();

Try a demo showcasing the close method.

collapseItem( item?: HTMLElement | string, animation?: boolean): voidCollapses a currently expanded item, hiding its content from view and displaying only the header or summary. This is typically used in expandable/collapsible components such as accordions or dropdown menus.

Collapses a currently expanded item, hiding its content from view and displaying only the header or summary. This is typically used in expandable/collapsible components such as accordions or dropdown menus.

Arguments

item?HTMLElement | string

smart-menu-item/smart-menu-items-group or its id or numeric path. If no item is passed, all open items are collapsed.

animation?boolean

If set to false, disables collapse animation even if animation is enabled for the element.

On the custom element in the DOM (narrow the selector, e.g. to #my-menu, if you host multiple widgets):

document.querySelector('smart-menu')?.collapseItem("0.0");

expandItem( item: HTMLElement | string, animation?: boolean): voidDisplays the detailed content or additional information of an item by expanding its view, typically used in accordions, dropdowns, or collapsible sections.

Displays the detailed content or additional information of an item by expanding its view, typically used in accordions, dropdowns, or collapsible sections.

Arguments

itemHTMLElement | string

smart-menu-item/smart-menu-items-group or its id or numeric path.

animation?boolean

If set to false, disables expand animation even if animation is enabled for the element.

On the custom element in the DOM (narrow the selector, e.g. to #my-menu, if you host multiple widgets):

document.querySelector('smart-menu')?.expandItem("1.2");

getItem( id: string): HTMLElementRetrieves a specific item using either its unique identifier (ID) or a numeric path value. This allows you to access an item directly by providing its assigned ID or by specifying its position within a structured path.

Retrieves a specific item using either its unique identifier (ID) or a numeric path value. This allows you to access an item directly by providing its assigned ID or by specifying its position within a structured path.

Arguments

idstring

The id or numeric path of an item

ReturnsHTMLElement

On the custom element in the DOM (narrow the selector, e.g. to #my-menu, if you host multiple widgets):

const result = document.querySelector('smart-menu')?.getItem("0.0");

maximize(): voidExpands the menu to display all available options, maximizing its visibility and accessibility for the user.

Expands the menu to display all available options, maximizing its visibility and accessibility for the user.

On the custom element in the DOM (narrow the selector, e.g. to #my-menu, if you host multiple widgets):

document.querySelector('smart-menu')?.maximize();

minimize(): voidCollapses the navigation menu to its minimized or compact state, reducing its visible size to save screen space while still providing access to essential menu options.

Collapses the navigation menu to its minimized or compact state, reducing its visible size to save screen space while still providing access to essential menu options.

On the custom element in the DOM (narrow the selector, e.g. to #my-menu, if you host multiple widgets):

document.querySelector('smart-menu')?.minimize();

open( left: number, top: number): voidOpens the Menu component only when the mode property is set to 'dropDown'. In this mode, the Menu will become visible in a dropdown format, allowing users to interact with its items. If mode is set to any other value, the Menu will not open.

Opens the Menu component only when the mode property is set to 'dropDown'. In this mode, the Menu will become visible in a dropdown format, allowing users to interact with its items. If mode is set to any other value, the Menu will not open.

Arguments

leftnumber

Horizontal position

topnumber

Vertical position

On the custom element in the DOM (narrow the selector, e.g. to #my-menu, if you host multiple widgets):

document.querySelector('smart-menu')?.open();

Try a demo showcasing the open method.

removeItem( item: HTMLElement | string): voidRemoves a specified item from the menu, updating the menu structure to reflect the change. This action ensures the targeted menu item is no longer displayed or accessible within the menu interface.

Removes a specified item from the menu, updating the menu structure to reflect the change. This action ensures the targeted menu item is no longer displayed or accessible within the menu interface.

Arguments

itemHTMLElement | string

The smart-menu-item/smart-menu-items-group or its id or numeric path to remove.

On the custom element in the DOM (narrow the selector, e.g. to #my-menu, if you host multiple widgets):

document.querySelector('smart-menu')?.removeItem("0.0");

Try a demo showcasing the removeItem method.

uncheckItem( item: HTMLElement | string): voidUnselects or removes the checkmark from a selected item, indicating that it is no longer active, chosen, or included in the current selection.

Unselects or removes the checkmark from a selected item, indicating that it is no longer active, chosen, or included in the current selection.

Arguments

itemHTMLElement | string

smart-menu-item/smart-menu-items-group (or its id or numeric path)

On the custom element in the DOM (narrow the selector, e.g. to #my-menu, if you host multiple widgets):

document.querySelector('smart-menu')?.uncheckItem("0.0");

Try a demo showcasing the uncheckItem method.

CSS Variables

--smart-menu-default-widthvar()

Default value

"var(--smart-bar-width)"

smartMenu default width

--smart-menu-default-heightvar()

Default value

"var(--smart-bar-height)"

smartMenu default height

--smart-menu-vertical-default-widthvar()

Default value

"calc(var(--smart-bar-width) / 2)"

vertical and context smartMenu default width

--smart-menu-vertical-default-heightvar()

Default value

"var(--smart-bar-width)"

vertical and context smartMenu default height

--smart-menu-scroll-button-sizevar()

Default value

"calc(var(--smart-bar-height) / 1.5)"

smartMenu scroll buttons size. Horizontal Menu scroll buttons width = Vertical Menu scroll buttons height.

MenuItem

Defines a menu item.

Selector

smart-menu-item

Quick picks

disabledvalue

Properties

Ccheckedchecked
DdisabledControls whether the element is enabled or disabled. When set to true, the element is interactive and can receive user input; when set to false, the element is disabled, preventing user interaction and applying a disabled appearance as appropriate.
Llabellabel
Llevellevel
Sseparatorseparator
Sshortcutshortcut
Vvaluevalue

Properties

checkedboolean

Default value

true

HTML attribute:

<smart-menu-item checked></smart-menu-item>

disabledControls whether the element is enabled or disabled. When set to true, the element is interactive and can receive user input; when set to false, the element is disabled, preventing user interaction and applying a disabled appearance as appropriate.boolean

Controls whether the element is enabled or disabled. When set to true, the element is interactive and can receive user input; when set to false, the element is disabled, preventing user interaction and applying a disabled appearance as appropriate.

Default value

false

Examples

Markup and runtime examples for disabled:

HTML attribute:

<smart-menu-item disabled></smart-menu-item>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu-item');
el.disabled = false;

Read the current value:

const el = document.querySelector('smart-menu-item');
const disabled = el.disabled;

labelany

Default value

""

levelnumber

separatorboolean

Default value

true

HTML attribute:

<smart-menu-item separator></smart-menu-item>

shortcutstring

Default value

""

valueany

MenuItemsGroup

Defines a group of menu items.

Selector

smart-menu-items-group

Quick picks

disabledvalue

Properties

Ccheckablecheckable
Ccheckedchecked
CcheckModecheckMode
DdisabledSpecifies whether the element is enabled or disabled. When set to true, the element is disabled and cannot be interacted with by the user; when set to false, the element remains enabled and fully interactive.
DdropDownHeightdropDownHeight
Eexpandedexpanded
Llabellabel
Llevellevel
Sseparatorseparator
Vvaluevalue

Properties

checkableboolean

Default value

false

HTML attribute:

<smart-menu-items-group checkable></smart-menu-items-group>

checkedboolean

Default value

false

HTML attribute:

<smart-menu-items-group checked></smart-menu-items-group>

checkMode"checkbox" | "radioButton"

Default value

"checkbox"

disabledSpecifies whether the element is enabled or disabled. When set to true, the element is disabled and cannot be interacted with by the user; when set to false, the element remains enabled and fully interactive.boolean

Specifies whether the element is enabled or disabled. When set to true, the element is disabled and cannot be interacted with by the user; when set to false, the element remains enabled and fully interactive.

Default value

false

Examples

Markup and runtime examples for disabled:

HTML attribute:

<smart-menu-items-group disabled></smart-menu-items-group>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-menu-items-group');
el.disabled = false;

Read the current value:

const el = document.querySelector('smart-menu-items-group');
const disabled = el.disabled;

dropDownHeightnumber

expandedboolean

Default value

false

HTML attribute:

<smart-menu-items-group expanded></smart-menu-items-group>

labelany

Default value

""

levelnumber

separatorboolean

Default value

false

HTML attribute:

<smart-menu-items-group separator></smart-menu-items-group>

valueany