Menus define the navigation structure and organization of your application. They control how users access pages, objects, and features through a hierarchical menu system.
File Naming Convention: <menu_name>.menu.yml
The filename (without the .menu.yml extension) automatically becomes the menu's identifier. This eliminates the need for a redundant name property inside the file.
Examples:
main_menu.menu.yml → Menu identifier: main_menu
admin_menu.menu.yml → Menu identifier: admin_menu
user_profile.menu.yml → Menu identifier: user_profile
Files should use snake_case for multi-word names.
Property Type Required Description labelstringRequired Human-readable menu title. typestringOptional Menu type: main, sidebar, dropdown, toolbar, context. Default: main. descriptionstringOptional Internal description of menu purpose. iconstringOptional Icon identifier for the menu. itemsarrayRequired Menu items and structure. positionstringOptional Menu placement: top, left, right. collapsiblebooleanOptional Whether menu can be collapsed. default_collapsedbooleanOptional Initial collapse state. permissionsobjectOptional Access control for the menu. ai_contextobjectOptional AI-friendly context.
Primary application navigation.
# File: main_menu.menu.yml
label : Main Navigation
type : main
position : left
items :
# Dashboard
- label : Dashboard
icon : standard:home
path : /dashboard
# CRM Section
- label : CRM
icon : standard:account
items :
- label : Accounts
icon : standard:account
object : account
path : /accounts
- label : Contacts
icon : standard:contact
object : contact
path : /contacts
- label : Opportunities
icon : standard:opportunity
object : opportunity
path : /opportunities
- separator : true
- label : Reports
icon : standard:reports
items :
- label : Sales Pipeline
path : /reports/sales_pipeline
- label : Win/Loss Analysis
path : /reports/win_loss
# Projects Section
- label : Projects
icon : standard:project
items :
- label : All Projects
object : project
path : /projects
- label : My Projects
path : /projects/my
- label : Project Templates
path : /projects/templates
# Settings
- label : Settings
icon : standard:settings
path : /settings
permissions :
view : [ admin ]
ai_context :
intent : "Main application navigation menu"
domain : application
Contextual sidebar navigation.
# File: admin_sidebar.menu.yml
label : Administration
type : sidebar
position : left
collapsible : true
items :
# User Management
- label : Users & Access
icon : standard:user
items :
- label : Users
object : user
path : /admin/users
- label : Roles
object : role
path : /admin/roles
- label : Permission Sets
object : permission_set
path : /admin/permissions
# Data Management
- label : Data Management
icon : standard:data
items :
- label : Objects
path : /admin/objects
- label : Fields
path : /admin/fields
- label : Relationships
path : /admin/relationships
- separator : true
- label : Import Data
path : /admin/import
- label : Export Data
path : /admin/export
# System Configuration
- label : System
icon : standard:settings
items :
- label : Company Settings
path : /admin/company
- label : Email Configuration
path : /admin/email
- label : Integrations
path : /admin/integrations
- label : API Keys
path : /admin/api_keys
permissions :
view : [ admin , system_admin ]
ai_context :
intent : "Administrative configuration and management menu"
domain : administration
User actions or context menu.
# File: user_profile.menu.yml
label : User Profile
type : dropdown
trigger : avatar # What triggers the dropdown
items :
# User info (non-clickable header)
- type : header
label : $current_user.name
subtitle : $current_user.email
- separator : true
# Profile actions
- label : My Profile
icon : standard:user
path : /profile
- label : Account Settings
icon : standard:settings
path : /settings/account
- label : Preferences
icon : standard:preferences
path : /settings/preferences
- separator : true
# Quick actions
- label : Switch Organization
icon : standard:organization
action : switch_org
- label : Help & Support
icon : standard:help
path : /help
- separator : true
# Logout
- label : Logout
icon : standard:logout
action : logout
style : danger
ai_context :
intent : "User profile dropdown with account actions"
domain : user_interface
Right-click or action menu.
# File: record_actions.menu.yml
label : Record Actions
type : context
description : Context menu for record operations
items :
# View/Edit
- label : View Details
icon : standard:view
action : view_record
- label : Edit
icon : standard:edit
action : edit_record
permission : update
- separator : true
# Record actions
- label : Clone
icon : standard:copy
action : clone_record
permission : create
- label : Share
icon : standard:share
action : share_record
- separator : true
# Advanced actions
- label : Export
icon : standard:export
items :
- label : Export as PDF
action : export_pdf
- label : Export as Excel
action : export_excel
- separator : true
# Delete
- label : Delete
icon : standard:delete
action : delete_record
permission : delete
confirm : Are you sure you want to delete this record?
style : danger
ai_context :
intent : "Context menu for record-level operations"
domain : user_interface
Quick action toolbar.
# File: list_toolbar.menu.yml
label : List Toolbar
type : toolbar
position : top
items :
# Create button
- label : New
icon : standard:add
action : create_record
variant : primary
permission : create
# Bulk actions
- label : Actions
icon : standard:actions
type : dropdown
items :
- label : Bulk Edit
action : bulk_edit
- label : Bulk Delete
action : bulk_delete
confirm : Delete selected records?
- label : Export Selected
action : export_selected
# View options
- label : View
icon : standard:view
type : dropdown
items :
- label : List View
action : set_view_type
value : list
checked : true
- label : Kanban View
action : set_view_type
value : kanban
- label : Calendar View
action : set_view_type
value : calendar
# Filters
- label : Filter
icon : standard:filter
action : show_filters
badge : 2 # Show active filter count
# Refresh
- icon : standard:refresh
action : refresh
tooltip : Refresh data
ai_context :
intent : "Toolbar with quick actions for list views"
domain : user_interface
items :
- label : Dashboard
icon : standard:home
path : /dashboard
- label : Customers
icon : standard:account
object : customer
path : /customers
items :
- label : Sales
icon : standard:opportunity
items :
- label : Opportunities
path : /opportunities
- label : Quotes
path : /quotes
- label : Orders
path : /orders
items :
- label : Create Record
icon : standard:add
action : create_record
params :
object : customer
- label : Run Report
icon : standard:report
action : run_report
params :
report_id : sales_summary
items :
- label : Item 1
path : /item1
- separator : true
- label : Item 2
path : /item2
items :
- type : header
label : Recent Items
- label : Recent Item 1
path : /items/1
- label : Recent Item 2
path : /items/2
items :
# Static item
- label : All Projects
path : /projects
# Dynamic items from database
- type : dynamic
label : Recent Projects
source :
object : project
filters :
- field : owner_id
operator : "="
value : $current_user.id
sort :
- field : modified_at
direction : desc
limit : 5
template :
label : $record.name
path : /projects/$record.id
icon : standard:project
- label : Menu Item # Display text
icon : standard:home # Icon
path : /home # Navigation path
badge : 5 # Badge count
tooltip : Tooltip text # Hover text
- label : Delete
icon : standard:delete
style : danger # primary, secondary, success, danger, warning
variant : outline # solid, outline, ghost
size : medium # small, medium, large
- label : Option 1
checked : true # Checkbox/radio state
disabled : false # Disabled state
active : true # Active/selected state
loading : false # Loading state
- label : Item
path : /path
target : _blank # Link target
external : true # External link
download : true # Trigger download
Control menu visibility based on user permissions.
items :
- label : Admin Panel
path : /admin
permissions :
view : [ admin , system_admin ]
- label : Reports
path : /reports
permissions :
view : [ admin , manager , analyst ]
items :
- label : Customers
object : customer
path : /customers
permissions :
object : customer
operation : read
items :
- label : Sensitive Data
path : /sensitive
permissions :
condition :
field : $current_user.clearance_level
operator : ">="
value : 3
# Menu-level styling
style :
background : white
color : text-primary
border : true
shadow : true
rounded : true
width : 250 # pixels
# Item styling
items :
- label : Item
style :
background : blue-500
color : white
padding : 8
margin : 4
active_style :
background : blue-100
color : blue-700
border_left : 3px solid blue-700
font_weight : bold
hover_style :
background : gray-100
color : gray-900
# File: app_main_menu.menu.yml
label : Application Menu
type : main
position : left
collapsible : true
default_collapsed : false
style :
width : 260
background : white
shadow : true
items :
# Dashboard
- label : Dashboard
icon : standard:home
path : /
exact : true # Only active on exact match
# Sales Section
- type : header
label : SALES
- label : Leads
icon : standard:lead
object : lead
path : /leads
badge : $count.leads_unqualified
- label : Opportunities
icon : standard:opportunity
object : opportunity
path : /opportunities
- label : Accounts
icon : standard:account
object : account
path : /accounts
- label : Contacts
icon : standard:contact
object : contact
path : /contacts
# Marketing Section
- type : header
label : MARKETING
- label : Campaigns
icon : standard:campaign
object : campaign
path : /campaigns
- label : Email Templates
icon : standard:email
path : /email_templates
# Service Section
- type : header
label : SERVICE
- label : Cases
icon : standard:case
object : case
path : /cases
badge : $count.cases_open
badge_style : danger
- label : Knowledge Base
icon : standard:knowledge
path : /knowledge
# Separator
- separator : true
# Analytics
- label : Reports & Dashboards
icon : standard:reports
items :
- label : Sales Reports
path : /reports/sales
- label : Service Reports
path : /reports/service
- separator : true
- label : Dashboards
path : /dashboards
# Separator
- separator : true
# Admin (conditional)
- label : Setup
icon : standard:settings
path : /setup
permissions :
view : [ admin ]
ai_context :
intent : "Main navigation for CRM application"
domain : crm
# File: opportunity_actions.menu.yml
label : Opportunity Actions
type : dropdown
description : Actions available on opportunity records
items :
# Quick actions
- label : Edit
icon : standard:edit
action : edit_record
keyboard_shortcut : e
- label : Clone
icon : standard:copy
action : clone_record
- label : Share
icon : standard:share
action : share_record
- separator : true
# Stage progression
- label : Advance Stage
icon : standard:forward
action : advance_stage
disabled_when :
field : stage
operator : "="
value : closed_won
- label : Mark as Won
icon : standard:success
action : mark_won
style : success
- label : Mark as Lost
icon : standard:close
action : mark_lost
style : danger
- separator : true
# Related actions
- label : Create Quote
icon : standard:quote
action : create_related
params :
object : quote
- label : Schedule Meeting
icon : standard:event
action : create_related
params :
object : event
- separator : true
# Export
- label : Export
icon : standard:export
items :
- label : PDF Summary
action : export_pdf
- label : Excel Details
action : export_excel
- separator : true
# Delete
- label : Delete
icon : standard:delete
action : delete_record
style : danger
confirm : Delete this opportunity?
permission : delete
ai_context :
intent : "Contextual actions for opportunity records"
domain : sales
# File: quick_create.menu.yml
label : Create New
type : dropdown
description : Quick create menu for common objects
trigger :
type : button
icon : standard:add
label : New
variant : primary
items :
# Frequently used
- type : header
label : QUICK CREATE
- label : Lead
icon : standard:lead
action : create_record
params :
object : lead
keyboard_shortcut : "cmd+shift+l"
- label : Contact
icon : standard:contact
action : create_record
params :
object : contact
keyboard_shortcut : "cmd+shift+c"
- label : Opportunity
icon : standard:opportunity
action : create_record
params :
object : opportunity
keyboard_shortcut : "cmd+shift+o"
- label : Task
icon : standard:task
action : create_record
params :
object : task
defaults :
assignee_id : $current_user.id
due_date : $tomorrow
keyboard_shortcut : "cmd+shift+t"
- separator : true
# More options
- label : More...
icon : standard:more
items :
- label : Account
icon : standard:account
action : create_record
params :
object : account
- label : Case
icon : standard:case
action : create_record
params :
object : case
- label : Campaign
icon : standard:campaign
action : create_record
params :
object : campaign
ai_context :
intent : "Quick access to create common records"
domain : productivity
Logical grouping : Group related items together
Limit depth : Keep menu hierarchy shallow (max 3 levels)
Use separators : Visually separate different groups
Meaningful labels : Use clear, descriptive labels
Lazy load : Load submenu items on demand
Cache permissions : Cache permission checks
Optimize queries : Efficient database queries for dynamic items
Debounce search : Debounce search in large menus
Keyboard shortcuts : Support keyboard navigation
Search functionality : Add search for large menus
Highlight active : Clearly show current location
Responsive design : Adapt to different screen sizes
ARIA labels : Use proper ARIA attributes
Keyboard navigation : Full keyboard support
Focus management : Proper focus handling
Screen reader : Ensure screen reader compatibility
Menus integrate with:
Pages : Navigate to page definitions
Objects : Link to object list/detail pages
Actions : Trigger custom actions
Permissions : Respect access control
Apps : Organize by application context
items :
# Generate menu from app definitions
- type : dynamic
source : apps
template :
label : $app.label
icon : $app.icon
items :
type : dynamic
source : $app.objects
template :
label : $object.label_plural
icon : $object.icon
path : /objects/$object.name