(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Overflow Menu

Overview

• The Dynamic Overflow Menu Component is a dropdown menu usually shown as an icon button.
• When activated, it displays a list of selectable options.
• It is useful for contextual actions, secondary features, or extra options without cluttering the interface.
• The component can be customized with icons, placement options, and menu items.
• It helps keep interfaces clean while still providing access to important functionality.

Specs

Tokens

Structure

(Configured in General Properties)

• displayName – Sets the display name of the component shown in the structure panel. For example, "Action Menu" clearly identifies the purpose of this overflow menu in the component structure.

(Configured in Visibility)

• displayConditions – Defines conditions under which the overflow menu is displayed. This allows for context-aware visibility, showing the menu only when certain conditions are met.

(Configured in Visual Properties)

• options – Defines the menu items that appear when the overflow menu is opened. Each option can have properties such as:
• text: The label shown for the menu item
• showMenuLinkIcon: Whether to display an icon next to the menu item text
• iconPositionKey: Where to place the icon ("menuLinkLeftIconName" or "menuLinkRightIconName")
• menuLinkLeftIconName / menuLinkRightIconName: The specific icon to display

• Menu Option Configuration – The overflow menu options can be extensively configured:

[
  {
    "text": "Edit Item",
    "type": "menu-link",
    "showMenuLinkIcon": true,
    "iconPositionKey": "menuLinkLeftIconName",
    "menuLinkLeftIconName": "edit-outline",
    "events": [
      {
        "type": "ON_OPTION_CLICK",
        "actions": [
          {
            "type": "NAVIGATE_TO_URL",
            "configuration": {
              "url": "/edit/{id}"
            }
          }
        ]
      }
    ]
  },
  {
    "text": "Delete Item",
    "type": "menu-link",
    "showMenuLinkIcon": true,
    "iconPositionKey": "menuLinkLeftIconName",
    "menuLinkLeftIconName": "delete-outline",
    "events": [
      {
        "type": "ON_OPTION_CLICK",
        "actions": [
          {
            "type": "SHOW_CONFIRMATION_DIALOG",
            "configuration": {
              "title": "Confirm Deletion",
              "message": "Are you sure you want to delete this item?"
            }
          }
        ]
      }
    ]
  }
]

Styling

(Configured in Visual Properties)

• iconName – Sets the icon displayed for the overflow menu button. For example, setting this to "more-outline" creates a three-dot menu icon, while "settings-outline" creates a gear icon that suggests configuration options.

• placement – Determines where the dropdown menu appears relative to the button. Options include "top", "right", "bottom", and "left". For example, setting this to "bottom" makes the menu appear below the button, which is useful when the component is placed near the top of the screen.

• paddingClass – Configures the padding around the component using CSS classes. For example, "p-2" adds medium padding on all sides of the overflow menu button.

Actions & Variants

(Configured in Events)

• events – Configures events that the component can trigger and respond to:
• ON_INIT – Triggered when the component is initialized. This event can be used for initial setup or configuration.
• ON_DESTROY – Triggered when the component is removed from the DOM. This event can be used for cleanup operations.
• ON_OPTION_CLICK – Triggered when a specific menu option is clicked. This event can be configured for each individual menu option to perform different actions.

Tests

(Configured in Testing Hooks)

• id – Specifies a unique identifier for the component, useful for programmatic access in testing or custom code.
• dataTestId – Sets a testing hook ID for automated testing, allowing test scripts to reliably identify this overflow menu component.
• enableAsHotspot – Enables the component as a guided tour hotspot. When enabled, this overflow menu can be highlighted during onboarding tours.
• guidedTourHotSpotTitle – Sets the title text displayed when this component is highlighted in a guided tour, with support for translations.
• guidedTourHotSpotDescription – Sets the descriptive text explaining the overflow menu's purpose during a guided tour, with support for translations.

Authorization

(Configured in Authorization)

• visibilityPolicySetId – Determines the visibility of the component based on user permissions and policy sets. For example, setting to "adminOnlyPolicy" restricts the overflow menu to users with admin privileges.

Guidelines

Common Use Cases

• Row actions in tables – Providing actions like Edit, Delete, Archive for individual table rows
• Page-level actions – Housing secondary actions that don't warrant primary button placement
• Settings menus – Offering configuration options in a compact dropdown
• Export options – Providing various export formats like PDF, Excel, CSV

Design Considerations

• Use consistent iconography that clearly communicates the menu's purpose
• Order menu items by frequency of use or logical grouping
• Consider adding dividers between logical groups of options
• Keep the number of options reasonable (generally fewer than 7–8 items)
• Use clear, concise labels for each option
• Add icons to options when they help with quick visual recognition
• This component helps maintain a clean, uncluttered interface while still providing access to important functionality when needed.

Usage

• Use the menu button icon to match intent. Set iconName to a generic “More” icon, or a generic "Settings" icon for configuration menus to set user expectation.
• Keep the list focused (≤ 7–8 items) to reduce decision time. Order by frequency or logical groups.
• Provide clear labels with options[n].text. Use short, action-first verbs (e.g., “Edit”, “Archive”).
• Add recognizable affordances where helpful: set options[n].showMenuLinkIcon plus iconPositionKey and either menuLinkLeftIconName or menuLinkRightIconName. Prefer left-placed icons for faster scanning.
• Name the instance meaningfully in authoring tools so teams can find it later: set displayName (e.g., "Row actions").

Sizing & Layout

• Control where the dropdown opens with placement: use "bottom" when the button is near the top edge; use "top" near the bottom; use "left"/"right" to avoid clipping against side gutters.
• Adjust hit-target and breathing room with paddingClass. For touch or glove scenarios, increase padding (e.g., "p-3" instead of "p-2").

States & Feedback

• Initialize data or compute context on load using events.ON_INIT (e.g., pre-build options, set displayConditions flags).
• Clean up listeners or ephemeral state with events.ON_DESTROY.
• Wire behavior per item with events.ON_OPTION_CLICK. Attach distinct handlers per options[n] to trigger navigation, mutations, or analytics.

Color & Contrast

• Don’t rely on color alone. Use options[n].showMenuLinkIcon with an appropriate …IconName to reinforce meaning. Choose icon names with distinct silhouettes via iconName/menuLink…IconName.

Interactions & Events

• For each menu item, bind a unique action via events.ON_OPTION_CLICK so telemetry and logic reflect the selected option.
• For onboarding, make the button discoverable by enabling its tour hotspot: set enableAsHotspot: true with guidedTourHotSpotTitle and guidedTourHotSpotDescription for the callout copy.

Data-Driven Behavior / Thresholds

• Show or hide the menu based on context with displayConditions (e.g., show only when a row is selected).
• Use events.ON_INIT to compute whether to include optional options (e.g., add “Undo” only when last action exists).

Visibility & Authorization

• Enforce permissions with visibilityPolicySetId so only authorized users see the menu (e.g., "adminOnlyPolicy").
• Combine with displayConditions to suppress the control in invalid contexts (e.g., non-editable states).

Content & Localization

• Keep options[n].text concise (2–3 words) and concrete (“Delete record”, not “Do operation”).
• If you highlight the menu in guided tours, localize the hotspot copy using guidedTourHotSpotTitle and guidedTourHotSpotDescription (both support translations).

Environment & Input Methods

• In industrial/touch contexts, prefer larger tap targets: increase paddingClass (e.g., "p-3"), and place icons left via iconPositionKey: "menuLinkLeftIconName" to support quick visual anchoring.
• When space is tight near edges, set placement to avoid off-screen rendering.

Testing Hooks

• Add stable selectors for automation with id and dataTestId (e.g., dataTestId: "row-ovrflow").

Do & Don’t

Accessibility

• Provide textual labels for every option via options[n].text; avoid icon-only entries so screen reader and low-vision users have clear labels.
• Don’t rely on color alone to convey meaning—pair color with an icon by setting options[n].showMenuLinkIcon, iconPositionKey, and menuLinkLeftIconName/menuLinkRightIconName.
• Increase the hit area for users with motor constraints (e.g., gloves) by using a larger paddingClass value such as "p-3".
• Keep the menu fully visible at high zoom or limited visual fields by choosing an appropriate placement ("top" | "right" | "bottom" | "left") to avoid off-screen clipping.
• Limit cognitive load: keep options focused (generally ≤ 7–8 items) and order by frequency so choices are easy to scan and decide.
• For guided onboarding, enable the hotspot and provide concise, descriptive copy with enableAsHotspot, guidedTourHotSpotTitle, and guidedTourHotSpotDescription; include translated text where applicable.