Context Menu

Guidelines
React API Reference
Blazor API Reference

Context menus provide contextual actions that appear when a user right-clicks (or performs an equivalent action) on an element. They offer a set of options relevant to the current context, allowing for efficient access to actions without cluttering the main interface.

Guidance

Aspect	Best Practice
Usage	Use context menus for secondary or specialized actions related to a specific element. These actions should be contextually relevant to the item.
Content	Group similar actions together. Include icons when helpful. Use clear, concise action labels. Consider including keyboard shortcuts when applicable.
Behavior	Position near the trigger point without extending beyond screen boundaries. Support keyboard navigation. Close on selection, Escape, or outside click.
States	Provide clear visual feedback for hover, focus, and disabled states. Clearly indicate submenus and their activation.
Feedback	Highlight items on hover/focus. Provide immediate visual feedback when an action is selected.
Examples	Document editing actions, file management options, data row operations, or object-specific commands.

Best Practices

Contextual Relevance: Only include actions that are meaningful in the current context.
Organization: Group related actions together and separate groups with dividers when appropriate.
Consistency: Maintain consistent positioning, styling, and behavior across the application.
Essential Actions: Include only the most relevant actions to avoid overwhelming users.
Accessibility: Ensure keyboard navigability and proper ARIA attributes for screen reader support.

Do’s and Don’ts

Do

Include only contextually relevant actions.
Group related items together with logical separators.
Provide keyboard navigation support.
Include descriptive labels and helpful icons.

Don't

Overload with too many options or levels of submenus.
Include primary actions that should be visible in the main UI.
Use as a replacement for main navigation.
Create inconsistent behaviors across different contexts.

Additional Guidance

Psychological Impact:
- Reduced Clutter: Context menus help maintain a clean main interface by tucking away secondary actions.
- Spatial Association: The proximity of the menu to the clicked element creates a strong mental connection between the item and its available actions.
- Expert User Support: Context menus are particularly valued by advanced users who appreciate efficient interaction patterns.

Import

import {
  ContextMenu,
  ContextMenuTrigger,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuShortcut,
  ContextMenuSub,
  ContextMenuSubTrigger,
  ContextMenuSubContent,
  ContextMenuSeparator,
  ContextMenuCheckboxItem
} from '@strongtie/design-system/context-menu';

Usage

<ContextMenu>
  <ContextMenuTrigger>Right click here</ContextMenuTrigger>
  <ContextMenuContent>
    <ContextMenuItem inset>
      Back
      <ContextMenuShortcut>⌘[</ContextMenuShortcut>
    </ContextMenuItem>
    <ContextMenuItem inset disabled>
      Forward
      <ContextMenuShortcut>⌘]</ContextMenuShortcut>
    </ContextMenuItem>
    <ContextMenuItem inset>
      Reload
      <ContextMenuShortcut>⌘R</ContextMenuShortcut>
    </ContextMenuItem>
    <ContextMenuSeparator />
    <ContextMenuCheckboxItem checked>
      Show Bookmarks
    </ContextMenuCheckboxItem>
    <ContextMenuCheckboxItem>
      Show Full URLs
    </ContextMenuCheckboxItem>
  </ContextMenuContent>
</ContextMenu>

`<ContextMenu>` Props

`<ContextMenuTrigger>` Props

asChild

boolean

default:"false"

If true, the trigger will render as a child component.

disabled

boolean

default:"false"

When true, the context menu won’t open.

`<ContextMenuContent>` Props

alignOffset

number

default:"0"

An offset in pixels from the “start” or “end” alignment options.

avoidCollisions

boolean

default:"true"

When true, overrides the side and align preferences to prevent collisions with boundary edges.

collisionBoundary

Element | null | Array<Element | null>

default:"[]"

The element used as the collision boundary.

collisionPadding

number | Partial<Record<Side, number>>

default:"0"

The distance in pixels from the boundary edges where collision detection should occur.

sticky

"partial" | "always"

default:"\"partial\""

The sticky behavior on the align axis.

`<ContextMenuItem>` Props

inset

boolean

default:"false"

When true, the item will have an inset appearance.

disabled

boolean

default:"false"

When true, prevents the user from interacting with the item.

onSelect

(event: Event) => void

Event handler called when the user selects an item.

textValue

string

Optional text used for typeahead purposes.

`<ContextMenuCheckboxItem>` Props

checked

boolean | 'indeterminate'

The controlled checked state of the item.

onCheckedChange

(checked: boolean) => void

Event handler called when the checked state changes.

disabled

boolean

default:"false"

When true, prevents the user from interacting with the item.

`<ContextMenuSub>` Props

defaultOpen

boolean

The open state of the submenu when it is initially rendered.

open

boolean

The controlled open state of the submenu.

onOpenChange

(open: boolean) => void

Event handler called when the open state of the submenu changes.

Usage Examples

<ContextMenu>
  <ContextMenuTrigger>
    Right click me
  </ContextMenuTrigger>
  <ContextMenuContent>
    <ContextMenuItem>
      Profile
    </ContextMenuItem>
    <ContextMenuItem>
      Settings
    </ContextMenuItem>
    <ContextMenuSeparator />
    <ContextMenuItem>
      Logout
    </ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>

Styling Classes

The component applies the following CSS classes:

context-menu-content - Applied to the main content container
context-menu-sub-content - Applied to submenu content containers
menu-item - Applied to all menu items (regular, checkbox, radio, label)
menu-item-sub-trigger - Applied to submenu trigger items
menu-item-checkbox - Applied to checkbox menu items
menu-item-radio - Applied to radio menu items
menu-item-label - Applied to label menu items
menu-item-indicator - Applied to checkbox/radio indicator spans
menu-item-separator - Applied to separator elements
menu-item-shortcut - Applied to shortcut text elements

For more examples, visit the Storybook.

Example

@inject ContextMenuService ContextMenuService

<StudsButton Text="Right click me" ContextMenu=@(args => ShowContextMenu(args)) />

@code {
    void ShowContextMenu(MouseEventArgs args)
    {
        ContextMenuService.Open(args,
            new List<ContextMenuItem> {
                new ContextMenuItem(){ Text = "Copy", Value = 1, Icon = "content_copy" },
                new ContextMenuItem(){ Text = "Paste", Value = 2, Icon = "content_paste", Disabled = true },
                new ContextMenuItem(){ Text = "Delete", Value = 3, Icon = "delete" },
        }, OnMenuItemClick);
    }

    void OnMenuItemClick(MenuItemEventArgs args)
    {
        ContextMenuService.Close();
        // Handle menu item click
    }
}

`ContextMenuService` Methods

Opens a context menu with the specified items and click handler.

Opens a context menu with custom content.

Close()

void

Closes the currently open context menu.

`ContextMenuItem` Properties

Text

string

The display text for the menu item.

Value

object

The value associated with the menu item, passed to the click handler.

Icon

string

The icon name to display next to the text.

IconColor

string

The color of the icon.

Image

string

Image URL to display instead of an icon.

ImageStyle

string

CSS styles to apply to the image.

Disabled

bool

default:"false"

Whether the menu item is disabled.

Usage Examples

@inject ContextMenuService ContextMenuService

<StudsButton Text="Right click me" ContextMenu=@ShowBasicContextMenu />

@code {
    void ShowBasicContextMenu(MouseEventArgs args)
    {
        ContextMenuService.Open(args,
            new List<ContextMenuItem> {
                new ContextMenuItem(){ Text = "Profile", Value = "profile" },
                new ContextMenuItem(){ Text = "Settings", Value = "settings" },
                new ContextMenuItem(){ Text = "Logout", Value = "logout" },
        }, OnMenuClick);
    }

    void OnMenuClick(MenuItemEventArgs args)
    {
        ContextMenuService.Close();
        // Handle the selected value
    }
}

Events

The context menu service provides several events for handling navigation and state changes:

OnOpen - Fired when a context menu is opened
OnClose - Fired when a context menu is closed
OnNavigate - Fired when navigation occurs (automatically closes menus)

Styling Classes

The following CSS classes are applied by the Context Menu components:

context-menu – Root context menu container
tooltip – Positioned container for the context menu

For more examples, visit the Storybook.

Getting Started

Foundations

Components

Integration Guides

Content

Context Menu

Guidance

Best Practices

Do’s and Don’ts

Do

Don't

Additional Guidance

`<ContextMenu>` Props

`<ContextMenuTrigger>` Props

`<ContextMenuContent>` Props

`<ContextMenuItem>` Props

`<ContextMenuCheckboxItem>` Props

`<ContextMenuSub>` Props

Usage Examples

Styling Classes

`ContextMenuService` Methods

`ContextMenuItem` Properties

Usage Examples

Events

Styling Classes

Getting Started

Foundations

Components

Integration Guides

Content

​Guidance

​Best Practices

​Do’s and Don’ts

Do

Don't

​Additional Guidance

​<ContextMenu> Props

​<ContextMenuTrigger> Props

​<ContextMenuContent> Props

​<ContextMenuItem> Props

​<ContextMenuCheckboxItem> Props

​<ContextMenuSub> Props

​Usage Examples

​Styling Classes

​ContextMenuService Methods

​ContextMenuItem Properties

​Usage Examples

​Events

​Styling Classes

Guidance

Best Practices

Do’s and Don’ts

Additional Guidance

`<ContextMenu>` Props

`<ContextMenuTrigger>` Props

`<ContextMenuContent>` Props

`<ContextMenuItem>` Props

`<ContextMenuCheckboxItem>` Props

`<ContextMenuSub>` Props

Usage Examples

Styling Classes

`ContextMenuService` Methods

`ContextMenuItem` Properties

Usage Examples

Events

Styling Classes