Page History

...

• 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

Usage

• Use the component to reveal contextual or secondary actions by configuring the trigger icon with iconName and the list of items with options.
• Place the dropdown where it will not obscure the trigger or key content by setting placement to "bottom", "top", "right", or "left" according to available space.
• Keep actions concise and scannable by writing clear labels in options[].text and, when recognition helps, enabling options[].showMenuLinkIcon to pair labels with icons.
• Keep menus lightweight by constraining the length of the options array to a manageable number (for example, around eight) so choices remain easy to scan.
• Use side-specific icons consistently by setting options[].iconPositionKey to "menuLinkLeftIconName" or "menuLinkRightIconName", and assigning options[].menuLinkLeftIconName or options[].menuLinkRightIconName accordingly.

Sizing & Layout

• Adjust the trigger’s tap/click comfort and breathing room using paddingClass (for example, "p-1", "p-2", "p-3") to align visually with nearby controls.
• Keep item alignment steady by choosing a single options[].iconPositionKey value so labels in options[].text line up across the list.
• Prevent clipping and reduce pointer travel by choosing an appropriate placement relative to the trigger using the "top", "right", "bottom", or "left" values.

States & Feedback

• Run setup logic at creation with ON_INIT (declared in events) when the menu should register analytics or prepare context for options.
• Perform cleanup on teardown with ON_DESTROY (declared in events) when initialization attached resources that need removal.
• Provide immediate feedback on selection by wiring per-item handlers in options[].events so ON_OPTION_CLICK triggers the intended action flow.

Interactions & Events

• Navigate or execute tasks by attaching actions to options[].events for the ON_OPTION_CLICK type; ensure the intent is reflected by clear options[].text.
• Gate destructive actions behind confirmation by routing ON_OPTION_CLICK in options[].events through a confirmation step before execution.
• Enable onboarding assistance by turning on enableAsHotspot and providing guidedTourHotSpotTitle and guidedTourHotSpotDescription so the trigger can be highlighted in a guided tour.

Data-Driven / Conditional Behavior

• Show only relevant actions for the current context by passing a context-appropriate options array to the component.
• Convey action semantics with icons by enabling options[].showMenuLinkIcon and setting options[].menuLinkLeftIconName or options[].menuLinkRightIconName consistently with options[].iconPositionKey.

Visibility & Authorization

• Show or hide the trigger based on context by defining displayConditions that resolve to true only when actions are applicable.
• Restrict access by setting visibilityPolicySetId so the overflow menu appears only for users in the permitted policy set.

Dos & Don’ts

Accessibility

Protocol of implemented accessibility measures

• Provide explicit, readable action labels with options[].text so assistive technologies can announce them clearly.
• Avoid meaning by color or icon alone by pairing options[].showMenuLinkIcon with text labels in options[].text.
• Reduce occlusion and surprise by selecting a predictable placement so the dropdown appears where users expect.
• Support automated checks and stable selectors by setting dataTestId and id.
• Improve onboarding comprehension by enabling enableAsHotspot and supplying descriptive guidedTourHotSpotTitle and guidedTourHotSpotDescription strings.

Practices to improve accessibility

• Prefer short, verb-led phrases in options[].text and avoid jargon to aid screen readers and translation.
• Keep icon placement consistent using options[].iconPositionKey so the reading order remains stable.
• Confirm destructive actions via options[].events using ON_OPTION_CLICK to present a confirmation step before the action proceeds.
• Ensure consistent placement across similar menus by standardizing placement within a product area.
• Populate dataTestId to integrate automated accessibility tests and regressions in pipelines
• 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.