syncfusion-react-context-menu

# Implementing Syncfusion React Context Menu **Complete API Reference & Feature Guide** ## When to Use This Skill ALWAYS use this skill when users need to: - **Install and configure** Syncfusion React ContextMenu component - **Create and manage menu items** (text, icons, separators, nested menus, URLs) - **Programmatically control** menus using 15+ methods - **Handle all 7 events** with their respective event arguments - **Customize appearance** with CSS classes, themes, templates, animations - **Bind data** from local sources or dynamic data structures - **Implement accessibility** (keyboard navigation, ARIA, RTL, WCAG 2.2) - **Manage dynamic menus** (add, remove, show, hide, enable/disable) - **Create context-specific actions** (files, editors, workflows) --- ## Getting Started 📄 **Read:** [references/getting-started.md](references/getting-started.md) - Package installation (`@syncfusion/ej2-react-navigations`) - Development environment setup (Vite, Create React App) - CSS stylesheet imports and theme configuration - Basic ContextMenu implementation - Running and testing the application --- ## Component Properties Reference The ContextMenuComponent accepts 18+ configuration properties to control behavior, appearance, and interaction: ### Essential Properties #### `target` (Required) **Type:** `string` CSS selector for the element that triggers the context menu (right-click or touch-hold). ```ts <ContextMenuComponent target="#myElement" items={menuItems} /> ``` **Example:** Trigger on specific element ```ts function App() { return ( <div> <div id="target">Right-click here</div> <ContextMenuComponent target="#target" items={menuItems} /> </div> ); } ``` --- #### `items` (Required) **Type:** `MenuItemModel[]` Array of menu items to display. Each item can have text, icons, nested items, separators, etc. ```ts const menuItems: MenuItemModel[] = [ { text: 'Cut' }, { text: 'Copy' }, { text: 'Paste' }, { separator: true }, { text: 'More', items: [ { text: 'Properties' }, { text: 'Delete' } ] } ]; <ContextMenuComponent target="#target" items={menuItems} /> ``` --- ### Display & Animation Properties #### `animationSettings` **Type:** `MenuAnimationSettingsModel` Configure menu opening/closing animation effects. **Properties:** - `effect`: Animation type (None, SlideDown, ZoomIn, FadeIn) - `duration`: Animation time in milliseconds (default: 400) - `easing`: CSS easing function (default: ease) ```ts const animationSettings = { effect: 'FadeIn', duration: 300, easing: 'ease-out' }; <ContextMenuComponent target="#target" items={menuItems} animationSettings={animationSettings} /> ``` **Available Effects:** | Effect | Description | |--------|-------------| | `None` | No animation | | `SlideDown` | Slide down from top | | `ZoomIn` | Zoom in effect | | `FadeIn` | Fade in opacity | --- #### `cssClass` **Type:** `string` Add custom CSS classes to the ContextMenu wrapper for custom styling. ```ts <ContextMenuComponent target="#target" items={menuItems} cssClass="custom-menu dark-theme" /> ``` --- #### `enableScrolling` **Type:** `boolean` (default: false) Enable scrolling when menu height exceeds available space. ```ts <ContextMenuComponent target="#target" items={largeMenuList} enableScrolling={true} /> ``` --- ### Interaction Properties #### `filter` **Type:** `string` CSS selector for specific elements inside the target that should trigger the context menu. Use to limit context menu to certain child elements. ```ts // Context menu only appears on table rows, not the entire table <ContextMenuComponent target="#table" filter="tr" items={menuItems} /> ``` --- #### `hoverDelay` **Type:** `number` (default: 400) Milliseconds to wait before displaying submenu on hover. ```ts <ContextMenuComponent target="#target" items={menuItems} hoverDelay={500} // 500ms before submenu appears /> ``` --- #### `showItemOnClick` **Type:** `boolean` (default: false) Force submenus to open only on click (not on hover). When `true`, arrow key navigation is required to open submenus. ```ts <ContextMenuComponent target="#target" items={menuItems} showItemOnClick={true} // Submenus open on click only /> ``` --- ### Data & Content Properties #### `itemTemplate` **Type:** `string | Function` Custom HTML template for menu items. Use template string with property placeholders (`${propertyName}`). ```ts const template = ` <div class="menu-item"> <span class="${iconCss}"></span> <span>${text}</span> <span class="shortcut">${shortcut}</span> </div> `; <ContextMenuComponent target="#target" items={menuItems} itemTemplate={template} /> ``` --- #### `locale` **Type:** `string` (default: 'en-US') Set localization language for component. Overrides global culture setting. ```ts <ContextMenuComponent target="#target" items={menuItems} locale="es-ES" // Spanish localization /> ``` --- ### Security & State Properties #### `enableHtmlSanitizer` **Type:** `boolean` (default: true) Enable HTML sanitization to prevent XSS attacks. Sanitizes untrusted HTML in menu items. ```ts <ContextMenuComponent target="#target" items={menuItems} enableHtmlSanitizer={true} // Sanitize HTML content /> ``` --- #### `enablePersistence` **Type:** `boolean` (default: false) Persist component state (expanded/collapsed state) across page reloads using browser storage. ```ts <ContextMenuComponent target="#target" items={menuItems} enablePersistence={true} /> ``` --- #### `enableRtl` **Type:** `boolean` (default: false) Enable right-to-left (RTL) layout for Arabic, Hebrew, and other RTL languages. ```ts <ContextMenuComponent target="#target" items={menuItems} enableRtl={true} /> ``` --- ## Menu Item Model Properties Each menu item is configured using `MenuItemModel` interface with the following properties: ### Text & Display #### `text` **Type:** `string` Display text for the menu item. ```ts { text: 'Cut' } { text: 'Copy' } ``` --- #### `id` **Type:** `string` Unique identifier for the menu item. Use for identifying items in event handlers or programmatic operations. ```ts { id: 'cut-item', text: 'Cut' } { id: 'copy-item', text: 'Copy' } ``` --- #### `iconCss` **Type:** `string` CSS class for icon display. Supports Syncfusion icons or custom icon classes. ```ts { text: 'Cut', iconCss: 'e-icons e-cut' } { text: 'Copy', iconCss: 'e-icons e-copy' } { text: 'Delete', iconCss: 'e-icons e-delete' } ``` --- ### Item Structure #### `items` **Type:** `MenuItemModel[]` Nested submenu items. Creates hierarchical menu structure. ```ts { text: 'File', items: [ { text: 'New' }, { text: 'Open' }, { text: 'Save' } ] } ``` --- #### `separator` **Type:** `boolean` (default: false) Render as a visual separator line instead of a clickable item. ```ts const menuItems: MenuItemModel[] = [ { text: 'Cut' }, { text: 'Copy' }, { separator: true }, // Visual divider { text: 'Delete' } ]; ``` --- ### Navigation #### `url` **Type:** `string` Navigation URL. Creates an anchor link that navigates when clicked. ```ts { text: 'Visit Site', url: 'https://example.com' } { text: 'Documentation', url: '/docs' } ``` --- ### Custom Attributes #### `htmlAttributes` **Type:** `Record<string, string>` Add custom HTML attributes to menu item element. ```ts { text: 'Download', htmlAttributes: { 'data-action': 'download', 'aria-label': 'Download file', 'title': 'Download the file' } } ``` --- ## Menu Methods – Programmatic Control The ContextMenu exposes 15+ methods for runtime control and manipulation: ### Menu State Control #### `open(top: number, left: number, target?: HTMLElement): void` Programmatically open the context menu at specified coordinates. **Parameters:** - `top`: Vertical position (Y-coordinate in pixels) - `left`: Horizontal position (X-coordinate in pixels) - `target`: Optional HTML element for z-index calculation ```ts function App() { const menuRef = React.useRef<ContextMenuComponent>(null); const openMenuAtClick = (event: React.MouseEvent) => { menuRef.current?.open(event.clientY, event.clientX); }; return ( <div> <button onClick={openMenuAtClick}>Open Menu</button> <ContextMenuComponent ref={menuRef} target="#target" items={menuItems} /> </div> ); } ``` --- #### `close(): void` Programmatically close the context menu. ```ts function App() { const menuRef = React.useRef<ContextMenuComponent>(null); const closeMenu = () => { menuRef.current?.close(); }; const handleItemSelect = (args: MenuEventArgs) => { console.log('Selected:', args.item?.text); closeMenu(); // Close menu after selection }; return ( <ContextMenuComponent ref={menuRef} target="#target" items={menuItems} select={handleItemSelect} /> ); } ``` --- ### Item Visibility Control #### `showItems(items: string[], isUniqueId?: boolean): void` Show menu items that were previously hidden. **Parameters:** - `items`: Array of item text or IDs to show - `isUniqueId`: If true, treat items as unique IDs; if false, treat as text (default: false) ```ts function App() {