---
metaTitle: Menu Configuration Reference | AwesCode UI
meta:
  - name: description
    content: Complete reference for configuring navigation menus in AwesCode UI applications.
title: Menu Configuration
---

# Menu Configuration Reference

Complete guide to configuring navigation menus in your AwesCode UI application.

## Overview

AwesCode UI uses Vuex to manage navigation menus. Menus are configured in plugins (typically `plugins/menu.js`) and stored in the `awesIo` store module.

## Menu Types

The framework supports four menu types:

1. **Main Menu** - Primary sidebar navigation
2. **Secondary Menu** - Additional navigation items
3. **User Menu** - User-specific actions (profile, logout, etc.)
4. **Tertiary Menu** - Additional context-specific menus

## Basic Menu Configuration

### Setup Menu Plugin

Create a menu plugin file (e.g., `plugins/menu.js`):

```javascript
export default function({ store, app }) {
    const menuItems = [
        {
            text: 'Dashboard',
            href: '/dashboard',
            icon: 'duotone/home'
        },
        {
            text: 'Customers',
            href: '/customers',
            icon: 'duotone/users'
        },
        {
            text: 'Settings',
            href: '/settings',
            icon: 'duotone/cog'
        }
    ]

    // Register menu items
    store.commit('awesIo/SET_MENU_ITEMS', { main: menuItems })
}
```

### Register Plugin in nuxt.config.js

```javascript
export default {
    plugins: [
        '~/plugins/menu.js'
    ]
}
```

## Menu Item Structure

### Basic Item

```javascript
{
    text: String,           // Display text (required)
    href: String | Function, // URL or function returning URL (required)
    icon: String,           // Icon name (optional)
    key: String,            // Unique identifier (optional, recommended)
    active: Boolean,        // Force active state (optional)
    exact: Boolean,         // Exact route match (optional, default: false)
    children: Array         // Submenu items (optional)
}
```

### Example with All Properties

```javascript
{
    text: 'Products',
    href: '/products',
    icon: 'duotone/box',
    key: 'products',
    exact: true,
    children: [
        { text: 'All Products', href: '/products' },
        { text: 'Categories', href: '/products/categories' },
        { text: 'Inventory', href: '/products/inventory' }
    ]
}
```

## Dynamic href Functions

Menu items can use functions for dynamic URLs based on application state:

```javascript
{
    text: 'Filters',
    icon: 'duotone/filter',
    key: 'filters',
    // Function receives Vuex state
    href: (state) => {
        // Desktop: redirect to first child
        if (state.awesIo.screen.lg) {
            return '/filters/overview'
        }
        // Mobile: show navigation hub
        return '/filters'
    },
    children: [
        { text: 'Overview', href: '/filters/overview' },
        { text: 'Date Filters', href: '/filters/date' },
        { text: 'Select Filters', href: '/filters/select' }
    ]
}
```

**When href Functions Are Evaluated:**
- On menu render
- When Vuex state changes (reactive)
- Useful for responsive navigation patterns

## Menu with Children (Submenus)

### Static Submenu

```javascript
{
    text: 'Settings',
    icon: 'duotone/cog',
    key: 'settings',
    href: '/settings',
    children: [
        { text: 'General', href: '/settings/general' },
        { text: 'Security', href: '/settings/security' },
        { text: 'Billing', href: '/settings/billing' },
        { text: 'Team', href: '/settings/team' }
    ]
}
```

### Mobile-Only Submenu Pattern

For sections where mobile users need a hub but desktop users go directly to content:

```javascript
{
    text: 'Documentation',
    icon: 'duotone/book',
    key: 'docs',
    // Mobile: show hub, Desktop: go to first child
    href: (state) => state.awesIo.screen.lg ? '/docs/getting-started' : '/docs',
    children: [
        { text: 'Getting Started', href: '/docs/getting-started' },
        { text: 'Components', href: '/docs/components' },
        { text: 'Guides', href: '/docs/guides' },
        { text: 'API Reference', href: '/docs/api' }
    ]
}
```

See [Mobile Subnavigation Pattern](../guides/mobile-subnavigation.md) for complete implementation guide.

## Setting Menu Items

### Main Menu

```javascript
store.commit('awesIo/SET_MENU_ITEMS', {
    main: [
        { text: 'Home', href: '/', icon: 'home' },
        { text: 'About', href: '/about', icon: 'info' }
    ]
})
```

### User Menu

```javascript
store.dispatch('awesIo/setUserMenu', [
    { text: 'Profile', href: '/profile', icon: 'user' },
    { text: 'Settings', href: '/settings', icon: 'cog' },
    { text: 'Logout', href: '/logout', icon: 'logout' }
])
```

### Multiple Menu Types

```javascript
store.commit('awesIo/SET_MENU_ITEMS', {
    main: [...],      // Primary navigation
    secondary: [...], // Secondary navigation
    tertiary: [...]   // Tertiary navigation
})
```

## Accessing Menu Items

### In Components

```markup
<script>
import { mapGetters } from 'vuex'

export default {
    computed: {
        ...mapGetters('awesIo', ['mainMenu', 'userMenu']),

        // Find specific menu item
        settingsMenu() {
            return this.mainMenu.find(item => item.key === 'settings')
        },

        // Get children from menu item
        settingsChildren() {
            return this.settingsMenu?.children || []
        }
    }
}
</script>
```

### Direct Store Access

```javascript
// Get main menu
const mainMenu = this.$store.getters['awesIo/mainMenu']

// Get user menu
const userMenu = this.$store.getters['awesIo/userMenu']

// Find menu item by key
const item = mainMenu.find(item => item.key === 'products')
```

## Icon Configuration

### Icon Naming Convention

Icons use the format: `{style}/{name}`

```javascript
// Duotone icons (recommended)
icon: 'duotone/home'
icon: 'duotone/users'
icon: 'duotone/cog'

// Solid icons
icon: 'solid/check'
icon: 'solid/star'

// Regular icons
icon: 'regular/bell'
icon: 'regular/heart'
```

### Available Icon Styles

- `duotone/` - Two-tone icons (most expressive)
- `solid/` - Filled icons
- `regular/` - Outlined icons
- `light/` - Light weight icons

See [AwIcon Component](../components/atoms/aw-icon.md) for complete icon reference.

## Best Practices

### Use Unique Keys

Always provide a `key` for menu items with children or that you need to reference:

```javascript
// ✅ Good - Easy to find and reference
{
    text: 'Filters',
    key: 'filters',
    href: '/filters',
    children: [...]
}

// ❌ Avoid - Harder to find reliably
{
    text: 'Filters',
    href: '/filters',
    children: [...]
}
```

### Menu Item Keys vs hrefs

```javascript
// Find by key (recommended)
const item = mainMenu.find(item => item.key === 'filters')

// Find by href (fallback)
const item = mainMenu.find(item => item.href === '/filters')

// Combined approach (most reliable)
const item = mainMenu.find(
    item => item.key === 'filters' || item.href === '/filters'
)
```

### Organize Menu by Feature

Group related menu items together:

```javascript
const menuItems = [
    // User Management
    { text: 'Customers', href: '/customers', icon: 'users' },
    { text: 'Teams', href: '/teams', icon: 'user-group' },

    // Product Management
    { text: 'Products', href: '/products', icon: 'box' },
    { text: 'Inventory', href: '/inventory', icon: 'warehouse' },

    // Settings
    { text: 'Settings', href: '/settings', icon: 'cog' }
]
```

### Dynamic Menu Items

Generate menu items programmatically:

```javascript
export default function({ store, app }) {
    const user = store.state.auth.user

    const menuItems = [
        { text: 'Dashboard', href: '/dashboard', icon: 'home' }
    ]

    // Add admin menu for admins only
    if (user.isAdmin) {
        menuItems.push({
            text: 'Admin',
            href: '/admin',
            icon: 'shield',
            children: [
                { text: 'Users', href: '/admin/users' },
                { text: 'Logs', href: '/admin/logs' }
            ]
        })
    }

    store.commit('awesIo/SET_MENU_ITEMS', { main: menuItems })
}
```

## Common Patterns

### Multi-Shop Menu

```javascript
{
    text: 'Shop Settings',
    icon: 'duotone/store',
    key: 'shop-settings',
    href: (state) => {
        const shopUuid = state.shop?.currentShop?.uuid
        return shopUuid ? `/shops/${shopUuid}/settings` : '/shops'
    },
    children: [
        {
            text: 'General',
            href: (state) => `/shops/${state.shop?.currentShop?.uuid}/settings/general`
        },
        {
            text: 'Team',
            href: (state) => `/shops/${state.shop?.currentShop?.uuid}/settings/team`
        }
    ]
}
```

### Conditional Menu Items

```javascript
const menuItems = [
    { text: 'Dashboard', href: '/dashboard', icon: 'home' }
]

// Add billing menu only if feature is enabled
if (features.billing) {
    menuItems.push({
        text: 'Billing',
        href: '/billing',
        icon: 'credit-card'
    })
}
```

### External Links

```javascript
{
    text: 'Help Center',
    href: 'https://help.example.com',
    icon: 'question-circle',
    // Opens in new tab
    target: '_blank'
}
```

## Troubleshooting

### Menu Not Updating

If menu items don't appear to update:

```javascript
// ❌ Don't mutate directly
this.$store.state.awesIo.mainMenu.push(newItem)

// ✅ Use commit
this.$store.commit('awesIo/SET_MENU_ITEMS', {
    main: [...this.$store.state.awesIo.mainMenu, newItem]
})
```

### Active State Not Working

Ensure routes match exactly or use `exact: false`:

```javascript
{
    text: 'Products',
    href: '/products',
    exact: false, // Will be active for /products and /products/123
    children: [...]
}
```

### Children Not Showing in AwSubnav

Verify menu item structure:

```javascript
// ✅ Correct
const item = mainMenu.find(item => item.key === 'filters')
console.log(item.children) // Should be an array

// Check in component
<AwSubnav v-if="item.children?.length" :children="item.children" />
```

## Related Documentation

- [Mobile Subnavigation Pattern](../guides/mobile-subnavigation.md) - Mobile navigation hubs
- [AwSubnav Component](../components/organisms/aw-subnav.md) - Sub-navigation component
- [AwLayout Component](../components/layouts/aw-layout.md) - Layout with menu integration
- [Getting Started - Menu Setup](../getting-started.md#menu-items) - Basic setup