ContextMenu

An enterprise-level context menu component based on BrConfigProvider for global theme configuration. It supports right-click triggering, nested submenus, adaptive positioning, and can seamlessly integrate with components like BrTable, BrTree, and BrCard. It also supports custom shortcut keys and full keyboard navigation.

Component Features

🖱️ Native Right-Click Hijacking: Perfectly replaces the browser's default context menu, providing a consistent UI experience.
📋 Nested Submenus: Supports infinitely nested submenus, suitable for complex hierarchical structures.
⌨️ Keyboard Accessibility: Fully supports keyboard navigation (up, down, left, right) and Esc to close, complying with W3C standards.
🎯 Adaptive Positioning: Automatically calculates the position based on the overlay engine to prevent the menu from being obscured at the edge of the screen.
🎨 Theme Customization: Supports global theme customization based on BrConfigProvider, as well as local style overrides using TailwindCSS.

Basic Usage

Right-click within the area to display a basic operation menu, containing normal items, disabled items, and shortcut key annotations.

<script setup lang="ts">
import {
  BrContextMenu,
  BrContextMenuTrigger,
  BrContextMenuContent,
  BrContextMenuItem,
  BrContextMenuSeparator
} from '@breezeui/vue'
</script>

<template>
  <BrContextMenu>
    <BrContextMenuTrigger class="flex h-[150px] w-full items-center justify-center rounded-md border border-dashed text-sm">
      Right-click here (Right click here)
    </BrContextMenuTrigger>
    <BrContextMenuContent class="w-64">
      <BrContextMenuItem shortcut="⌘[">
        Back (Back)
      </BrContextMenuItem>
      <BrContextMenuItem shortcut="⌘]" disabled>
        Forward (Forward)
      </BrContextMenuItem>
      <BrContextMenuItem shortcut="⌘R">
        Reload (Reload)
      </BrContextMenuItem>
      <BrContextMenuSeparator />
      <BrContextMenuItem shortcut="⌘S">
        Save As... (Save As...)
      </BrContextMenuItem>
      <BrContextMenuItem shortcut="⌘P">
        Print... (Print...)
      </BrContextMenuItem>
    </BrContextMenuContent>
  </BrContextMenu>
</template>

Nested Submenus

Supports multi-level nested submenus and automatically handles edge overflow issues.

<script setup lang="ts">
import {
  BrContextMenu,
  BrContextMenuTrigger,
  BrContextMenuContent,
  BrContextMenuItem,
  BrContextMenuSeparator,
  BrContextMenuSub,
  BrContextMenuSubTrigger,
  BrContextMenuSubContent
} from '@breezeui/vue'
</script>

<template>
  <BrContextMenu>
    <BrContextMenuTrigger class="flex h-[150px] w-full items-center justify-center rounded-md border border-dashed text-sm">
      Right-click to open nested menu (Right click to open nested menu)
    </BrContextMenuTrigger>
    <BrContextMenuContent class="w-64">
      <BrContextMenuItem>
        New File (New File)
      </BrContextMenuItem>
      <BrContextMenuItem>
        New Folder (New Folder)
      </BrContextMenuItem>
      <BrContextMenuSeparator />
      <BrContextMenuSub>
        <BrContextMenuSubTrigger>
          Open With (Open With)
        </BrContextMenuSubTrigger>
        <BrContextMenuSubContent class="w-48">
          <BrContextMenuItem>Breeze Code</BrContextMenuItem>
          <BrContextMenuItem>System Default (System Default)</BrContextMenuItem>
          <BrContextMenuSeparator />
          <BrContextMenuItem>Select Other App... (Choose other app...)</BrContextMenuItem>
        </BrContextMenuSubContent>
      </BrContextMenuSub>
      <BrContextMenuSeparator />
      <BrContextMenuItem shortcut="⌘⌫" class="text-destructive focus:text-destructive-foreground">
        Delete (Delete)
      </BrContextMenuItem>
    </BrContextMenuContent>
  </BrContextMenu>
</template>

Integration with Card

Bind right-click operations to cards or complex areas. You can use as-child to merge the trigger properties onto custom components.

<script setup lang="ts">
import {
  BrContextMenu,
  BrContextMenuTrigger,
  BrContextMenuContent,
  BrContextMenuItem,
  BrContextMenuSeparator,
  BrCard,
  BrCardHeader,
  BrCardTitle,
  BrCardDescription,
  BrCardContent
} from '@breezeui/vue'
</script>

<template>
  <BrContextMenu>
    <BrContextMenuTrigger as-child>
      <BrCard class="w-[350px] cursor-context-menu transition-shadow hover:shadow-md">
        <BrCardHeader>
          <BrCardTitle>Breeze UI Project (Breeze UI Project)</BrCardTitle>
          <BrCardDescription>Right-click the card to view actions (Right click card to see actions)</BrCardDescription>
        </BrCardHeader>
        <BrCardContent>
          The current project contains various enterprise-level UI Components。
          (This project contains various enterprise-level UI components.)
        </BrCardContent>
      </BrCard>
    </BrContextMenuTrigger>
    
    <BrContextMenuContent class="w-48">
      <BrContextMenuItem>Pin project (Pin Project)</BrContextMenuItem>
      <BrContextMenuItem>Share link... (Share Link...)</BrContextMenuItem>
      <BrContextMenuSeparator />
      <BrContextMenuItem>Rename (Rename)</BrContextMenuItem>
      <BrContextMenuItem class="text-destructive focus:text-destructive">Delete project (Delete Project)</BrContextMenuItem>
    </BrContextMenuContent>
  </BrContextMenu>
</template>

Table Row Operations

Demonstrates how to seamlessly integrate the context menu with a data table, binding right-click events to each row.

<script setup lang="ts">
import { ref } from 'vue'
import {
  BrContextMenu,
  BrContextMenuTrigger,
  BrContextMenuContent,
  BrContextMenuItem,
  BrContextMenuSeparator
} from '@breezeui/vue'

const tableData = ref([
  { id: 1, name: 'Breeze-Core', status: 'Active' },
  { id: 2, name: 'Breeze-Vue', status: 'Developing' },
])

const handleAction = (action: string, row: any) => {
  console.log(`Execute action: ${action} on project: ${row.name}`)
}
</script>

<template>
  <div class="rounded-md border">
    <table class="w-full text-sm">
      <thead>
        <tr class="border-b bg-muted/50 text-left">
          <th class="p-4 font-medium">Project Name (Project Name)</th>
          <th class="p-4 font-medium">Status (Status)</th>
        </tr>
      </thead>
      <tbody>
        <template v-for="row in tableData" :key="row.id">
          <BrContextMenu>
            <!-- as-child Allows merging trigger attributes into native tr elements -->
            <BrContextMenuTrigger as-child>
              <tr class="border-b transition-colors hover:bg-muted/50 cursor-context-menu">
                <td class="p-4">{{ row.name }}</td>
                <td class="p-4">{{ row.status }}</td>
              </tr>
            </BrContextMenuTrigger>
            <BrContextMenuContent>
              <BrContextMenuItem @select="handleAction('View', row)">View Details (View Details)</BrContextMenuItem>
              <BrContextMenuItem @select="handleAction('Edit', row)">Edit (Edit)</BrContextMenuItem>
              <BrContextMenuSeparator />
              <BrContextMenuItem class="text-destructive focus:text-destructive" @select="handleAction('Delete', row)">Delete (Delete)</BrContextMenuItem>
            </BrContextMenuContent>
          </BrContextMenu>
        </template>
      </tbody>
    </table>
  </div>
</template>

Theme Customization

The style of BrContextMenu is fully integrated with the BrConfigProvider system. You can adjust its appearance globally or locally by configuring CSS variables.

<script setup lang="ts">
import {
  BrContextMenu,
  BrContextMenuTrigger,
  BrContextMenuContent,
  BrContextMenuItem,
  BrConfigProvider
} from '@breezeui/vue'
</script>

<template>
  <BrConfigProvider
    :theme="{
      radius: '0.25rem',
      popover: '#f8fafc',
      popoverForeground: '#0f172a',
    }"
  >
    <BrContextMenu>
      <BrContextMenuTrigger class="flex h-[150px] w-full items-center justify-center rounded-md border border-dashed text-sm">
        Right-click to view custom theme (Right click to view custom theme)
      </BrContextMenuTrigger>
      <BrContextMenuContent class="w-64">
        <BrContextMenuItem>Custom Theme Item 1 (Custom Theme Item 1)</BrContextMenuItem>
        <BrContextMenuItem>Custom Theme Item 2 (Custom Theme Item 2)</BrContextMenuItem>
        <BrContextMenuItem class="focus:bg-blue-500 focus:text-white">
          Local Override Style Item (Local override style item)
        </BrContextMenuItem>
      </BrContextMenuContent>
    </BrContextMenu>
  </BrConfigProvider>
</template>

API Reference

BrContextMenu

The root component that wraps the entire context menu, responsible for managing the right-click state and events.

Property	Type	Default	Description
`dir`	`'ltr' \| 'rtl'`	`'ltr'`	The reading direction of the menu
`modal`	`boolean`	`true`	Whether it is modal (prevents outside interaction when open)

Event	Type	Description
`@update:open`	`(open: boolean) => void`	Triggered when the menu opens or closes

BrContextMenuTrigger

The area that triggers the menu.

Property	Type	Default	Description
`asChild`	`boolean`	`false`	Whether to pass the trigger properties to the child element, used to replace the default wrapper span/div
`class`	`any`	-	Custom class name

BrContextMenuContent

The container for the menu content after right-clicking.

Property	Type	Default	Description
`alignOffset`	`number`	`0`	Alignment offset
`avoidCollisions`	`boolean`	`true`	Whether to automatically avoid screen edges
`collisionBoundary`	`Element \| Element[]`	`[]`	Collision detection boundary
`collisionPadding`	`number \| Record`	`0`	Collision detection padding
`loop`	`boolean`	`false`	Whether keyboard navigation loops
`class`	`any`	-	Container class name

BrContextMenuItem

A single menu item.

Property	Type	Default	Description
`disabled`	`boolean`	`false`	Whether it is disabled
`textValue`	`string`	-	Text used for first-letter matching in keyboard navigation
`shortcut`	`string`	-	Shortcut key display text (e.g., `⌘P`)
`inset`	`boolean`	`false`	Whether to display indented (usually used to align items with icons)
`class`	`any`	-	Menu item class name

Event	Type	Description
`@select`	`(event: Event) => void`	Triggered when selected. Can call `event.preventDefault()` to prevent default closing behavior

BrContextMenuSub & BrContextMenuSubTrigger & BrContextMenuSubContent

Used to build nested submenus. Their properties are basically equivalent to the corresponding root container components, with added support for hover to expand/collapse.

BrContextMenuEmpty & BrContextMenuLoading

Preset placeholder components for handling empty data and asynchronous loading states.

Property	Type	Default	Description
`text`	`string`	`'No items' / 'Loading...'`	Prompt text

#ContextMenu

#Component Features

#Basic Usage

#Nested Submenus

#Integration with Card

#Table Row Operations

#Theme Customization

#API Reference

#BrContextMenu

#BrContextMenuTrigger

#BrContextMenuContent

#BrContextMenuItem

#BrContextMenuSub & BrContextMenuSubTrigger & BrContextMenuSubContent

#BrContextMenuEmpty & BrContextMenuLoading