--- type: ai-agent-documentation version: 2.0 component: Menu status: stable audience: ai-coding-agents-only human-readable: false category: navigation framework-support: - vanilla: true - react: true - vue: true - angular: true - svelte: true --- # Component: Menu DEFINITION: The Menu component provides accessible, keyboard-navigable dropdown menus for contextual actions or navigation. It consists of a trigger and a content panel with menu items. ## Installation ```bash npm install @pm7/core ``` ### CSS & JavaScript Import REQUIRED: Import both the CSS and the main JavaScript file. ```javascript // ES modules import '@pm7/core/dist/pm7.css'; import '@pm7/core'; // Imports and initializes all components // HTML ``` ## Required Structure The Menu component requires a main container with `data-pm7-menu`, a trigger button (`.pm7-menu-trigger`), and a content container (`.pm7-menu-content`) holding the menu items. ```html
``` ### Structural Rules - **ALWAYS**: The main menu container MUST have `data-pm7-menu`. - **ALWAYS**: The trigger MUST be a `
``` ### Pattern: Menu with Checkbox Items ```html
``` ### Pattern: Menu with Submenu ```html
``` ## Anti-Patterns ### NEVER: Use non-button elements for interactive menu items ```html
Link Item
Div Item
Non-button elements lack native keyboard support, ARIA semantics, and proper focus management, making the menu inaccessible.
``` ### NEVER: Omit `data-name` for radio menu items ```html Without a `data-name` attribute, radio items will not function as a mutually exclusive group. ``` ### NEVER: Manually position the menu content ```html
...
The Menu component automatically handles positioning based on the trigger, viewport, and `data-position` attribute. Manual positioning will conflict and break responsiveness.
...
``` ## React Integration > **📚 Framework Integration Guide**: For Vue, Angular, and other framework integrations, see the comprehensive [Framework Integration Guide](https://raw.githubusercontent.com/patrickmast/pm7-ui/main/README-Framework-Integration.md) ### ⚠️ CRITICAL: Event Handling in React PM7-UI menus require special handling in React due to event system conflicts: 1. **NEVER use React event handlers (onClick) on PM7 menu items** - React's synthetic events conflict with PM7's menu event handling - Use `dangerouslySetInnerHTML` with lowercase `onclick` attributes for custom menu actions 2. **The onclick vs onClick Problem** - React filters out lowercase HTML attributes like `onclick` - PM7 menu items use internal event delegation that conflicts with React's event system - Solution: Use `dangerouslySetInnerHTML` for custom menu items or handle events via PM7's event system 3. **Use PM7 Events for Menu Interactions** ```jsx useEffect(() => { const handleMenuSelect = (e) => { console.log('Menu item selected:', e.detail); // Handle menu selection in React }; document.addEventListener('pm7:menu:select', handleMenuSelect); return () => document.removeEventListener('pm7:menu:select', handleMenuSelect); }, []); ``` ### Complete React Example ```jsx function AppMenu() { const [selectedSort, setSelectedSort] = useState('name'); const [showGrid, setShowGrid] = useState(true); // Initialize PM7 useEffect(() => { window.PM7?.initFramework(); }, []); // Listen for PM7 menu events useEffect(() => { const handleMenuSelect = (e) => { const { value, menuId } = e.detail; if (menuId === 'sort-menu') { setSelectedSort(value); } }; const handleMenuChange = (e) => { const { checked, menuId } = e.detail; if (menuId === 'view-menu') { setShowGrid(checked); } }; document.addEventListener('pm7:menu:select', handleMenuSelect); document.addEventListener('pm7:menu:change', handleMenuChange); return () => { document.removeEventListener('pm7:menu:select', handleMenuSelect); document.removeEventListener('pm7:menu:change', handleMenuChange); }; }, []); return (
Sort By

View Options

` }} />
); } ``` ### Handling Submenus in React For complex menus with submenus, the structure must be maintained exactly: ```jsx function ComplexMenu() { return (
New File
` }} />
); } ``` ### Key Points for React: - Always use `dangerouslySetInnerHTML` for menu content to preserve PM7's event handling - Listen to PM7 menu events (`pm7:menu:select`, `pm7:menu:change`) for state updates - Do not use React onClick handlers on menu items - Maintain the exact DOM structure for submenus - See [Framework Integration Guide](../../../../../../README-Framework-Integration.md) for more details ## Rules ### ALWAYS - **ALWAYS**: Use a `
john.doe@example.com
```