Catalog Menu

Overview

A catalog menu is the primary navigation element that allows customers to browse the store by category. It is built from Lunar’s collection hierarchy: collection groups organize top-level navigation sections, and collections within each group form nested trees of categories and subcategories. This guide walks through querying collection groups and their nested collections, rendering a multi-level navigation menu, highlighting the active collection, and caching the result for performance. The examples below use standard Laravel controllers and Blade templates. The same concepts apply whether the storefront is built with Livewire, Inertia, or a headless API.

How Collections Are Organized

Lunar organizes collections into a two-level structure:

Collection Groups act as top-level containers (e.g., “Main Menu”, “Footer Links”, “Seasonal Promotions”). Each group has a unique handle for identification.
Collections within a group form a nested tree using parent-child relationships. A root collection has no parent, and each root can have unlimited levels of children.

Main Menu (CollectionGroup)

Clothing

Men's

T-Shirts

Jackets

Women's

Dresses

Tops

Footwear

Sneakers

Boots

Accessories

Fetching a Collection Group

Retrieve a collection group by its handle. The handle is set when creating the group in the admin panel or via code.

use Lunar\Models\CollectionGroup;

$menuGroup = CollectionGroup::where('handle', 'main-menu')->first();

Fetching Root Collections

Root collections are those with no parent. Use the nested set’s whereIsRoot() scope to retrieve them.

use Lunar\Models\Collection;

$rootCollections = Collection::where('collection_group_id', $menuGroup->id)
    ->whereIsRoot()
    ->defaultOrder()
    ->with(['defaultUrl', 'media'])
    ->get();

The defaultOrder() scope orders collections by their nested set position, which matches the order configured in the admin panel.

Fetching Children

Each collection’s children can be loaded via the children relationship. To build a full menu tree, eager load the children (and their children) to avoid N+1 queries.

$rootCollections = Collection::where('collection_group_id', $menuGroup->id)
    ->whereIsRoot()
    ->defaultOrder()
    ->with([
        'defaultUrl',
        'children' => fn ($query) => $query->defaultOrder(),
        'children.defaultUrl',
        'children.children' => fn ($query) => $query->defaultOrder(),
        'children.children.defaultUrl',
    ])
    ->get();

This loads three levels of the menu hierarchy. Add additional children levels as needed for deeper menus.

Eager loading children with constrained queries (using the closure syntax) ensures each level is ordered correctly by its nested set position.

Using `descendantsOf` for the Full Tree

For menus that need the entire tree regardless of depth, the nested set provides a descendantsOf method. However, for navigation menus it is generally better to eager load a fixed number of levels to keep queries predictable and avoid loading unnecessary data.

// Load the entire subtree (all depths) for a collection group
$allCollections = Collection::where('collection_group_id', $menuGroup->id)
    ->defaultOrder()
    ->with('defaultUrl')
    ->get()
    ->toTree();

The toTree() method on the resulting collection restructures the flat list into a nested tree, with each node’s children relation populated. Encapsulate the menu query in a dedicated service class to keep controllers clean and make caching straightforward.

<?php

namespace App\Services;

use Illuminate\Support\Collection as LaravelCollection;
use Lunar\Models\Collection;
use Lunar\Models\CollectionGroup;

class CatalogMenuService
{
    public function getMenu(string $handle = 'main-menu', int $depth = 3): LaravelCollection
    {
        $group = CollectionGroup::where('handle', $handle)->first();

        if (! $group) {
            return collect();
        }

        $query = Collection::where('collection_group_id', $group->id)
            ->whereIsRoot()
            ->defaultOrder()
            ->with($this->buildEagerLoads($depth));

        return $query->get();
    }

    protected function buildEagerLoads(int $depth): array
    {
        $eagerLoads = ['defaultUrl'];
        $prefix = '';

        for ($i = 1; $i < $depth; $i++) {
            $prefix .= ($i === 1) ? 'children' : '.children';
            $eagerLoads[$prefix] = fn ($query) => $query->defaultOrder();
            $eagerLoads["{$prefix}.defaultUrl"] = fn ($query) => $query;
        }

        return $eagerLoads;
    }
}

use App\Services\CatalogMenuService;

$menu = app(CatalogMenuService::class)->getMenu('main-menu');

Use a view composer or middleware to make the menu available to every page without passing it from each controller.

<?php

namespace App\Providers;

use App\Services\CatalogMenuService;
use Illuminate\Support\Facades\View;
use Illuminate\Support\ServiceProvider;

class ViewServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        View::composer('*', function ($view) {
            $view->with(
                'catalogMenu',
                app(CatalogMenuService::class)->getMenu()
            );
        });
    }
}

When using a view composer with '*', the menu query runs on every request. Pair this with caching (covered below) to avoid repeated database queries.

<nav aria-label="Catalog navigation">
    <ul>
        @foreach($catalogMenu as $collection)
            <li>
                <a href="{{ route('collections.show', $collection->defaultUrl?->slug) }}">
                    {{ $collection->attr('name') }}
                </a>

                @if($collection->children->isNotEmpty())
                    <ul>
                        @foreach($collection->children as $child)
                            <li>
                                <a href="{{ route('collections.show', $child->defaultUrl?->slug) }}">
                                    {{ $child->attr('name') }}
                                </a>
                            </li>
                        @endforeach
                    </ul>
                @endif
            </li>
        @endforeach
    </ul>
</nav>

For menus with an arbitrary number of levels, use a recursive Blade partial. Create a partial at resources/views/partials/menu-item.blade.php:

<li>
    <a
        href="{{ route('collections.show', $collection->defaultUrl?->slug) }}"
        @if(isset($activeCollectionIds) && in_array($collection->id, $activeCollectionIds))
            aria-current="true"
        @endif
    >
        {{ $collection->attr('name') }}
    </a>

    @if($collection->children->isNotEmpty())
        <ul>
            @foreach($collection->children as $child)
                @include('partials.menu-item', ['collection' => $child])
            @endforeach
        </ul>
    @endif
</li>

Then render the top-level menu:

<nav aria-label="Catalog navigation">
    <ul>
        @foreach($catalogMenu as $collection)
            @include('partials.menu-item', ['collection' => $collection])
        @endforeach
    </ul>
</nav>

Active State Tracking

Highlighting the active collection (and its ancestors) helps customers understand where they are in the catalog hierarchy.

Determining the Active Collection

In the collection controller, pass the current collection and its ancestor IDs to the view:

use Lunar\Models\Collection;
use Lunar\Models\Url;

class CollectionController extends Controller
{
    public function show(string $slug)
    {
        $url = Url::where('slug', $slug)
            ->where('element_type', (new Collection)->getMorphClass())
            ->firstOrFail();

        $collection = Collection::where('id', $url->element_id)
            ->with(['ancestors', 'media'])
            ->firstOrFail();

        $activeCollectionIds = $collection->ancestors
            ->pluck('id')
            ->push($collection->id)
            ->all();

        return view('collections.show', [
            'collection' => $collection,
            'activeCollectionIds' => $activeCollectionIds,
        ]);
    }
}

Applying Active Styles

Share the active IDs with the layout so the menu partial can use them:

{{-- In the layout or menu partial --}}
<a
    href="{{ route('collections.show', $collection->defaultUrl?->slug) }}"
    @class([
        'menu-link',
        'active' => isset($activeCollectionIds) && in_array($collection->id, $activeCollectionIds),
    ])
>
    {{ $collection->attr('name') }}
</a>

This highlights both the current collection and all its parent collections in the menu, giving customers a clear visual trail.

Caching

The catalog menu changes infrequently compared to how often it is rendered. Caching prevents a database query on every page load. Update the CatalogMenuService to cache the menu:

<?php

namespace App\Services;

use Illuminate\Support\Collection as LaravelCollection;
use Illuminate\Support\Facades\Cache;
use Lunar\Models\Collection;
use Lunar\Models\CollectionGroup;

class CatalogMenuService
{
    public function getMenu(string $handle = 'main-menu', int $depth = 3): LaravelCollection
    {
        return Cache::remember(
            "catalog-menu:{$handle}",
            now()->addHour(),
            fn () => $this->buildMenu($handle, $depth)
        );
    }

    public function clearCache(string $handle = 'main-menu'): void
    {
        Cache::forget("catalog-menu:{$handle}");
    }

    protected function buildMenu(string $handle, int $depth): LaravelCollection
    {
        $group = CollectionGroup::where('handle', $handle)->first();

        if (! $group) {
            return collect();
        }

        return Collection::where('collection_group_id', $group->id)
            ->whereIsRoot()
            ->defaultOrder()
            ->with($this->buildEagerLoads($depth))
            ->get();
    }

    protected function buildEagerLoads(int $depth): array
    {
        $eagerLoads = ['defaultUrl'];
        $prefix = '';

        for ($i = 1; $i < $depth; $i++) {
            $prefix .= ($i === 1) ? 'children' : '.children';
            $eagerLoads[$prefix] = fn ($query) => $query->defaultOrder();
            $eagerLoads["{$prefix}.defaultUrl"] = fn ($query) => $query;
        }

        return $eagerLoads;
    }
}

Invalidating the Cache

Clear the cache whenever collections are updated. A model observer is a clean way to handle this:

<?php

namespace App\Observers;

use App\Services\CatalogMenuService;
use Lunar\Models\Collection;

class CollectionObserver
{
    public function __construct(
        protected CatalogMenuService $menuService,
    ) {}

    public function saved(Collection $collection): void
    {
        $this->menuService->clearCache();
    }

    public function deleted(Collection $collection): void
    {
        $this->menuService->clearCache();
    }
}

use App\Observers\CollectionObserver;
use Lunar\Models\Collection;

public function boot(): void
{
    Collection::observe(CollectionObserver::class);
}

Multiple Menus

A store may need more than one navigation menu, for example a main header menu and a footer menu. Use separate collection groups for each.

// Header menu
$headerMenu = app(CatalogMenuService::class)->getMenu('main-menu');

// Footer menu
$footerMenu = app(CatalogMenuService::class)->getMenu('footer-menu');

Share both via a view composer:

View::composer('*', function ($view) {
    $menuService = app(CatalogMenuService::class);

    $view->with('headerMenu', $menuService->getMenu('main-menu'));
    $view->with('footerMenu', $menuService->getMenu('footer-menu'));
});

Each menu is cached independently under its own key.

Channel and Customer Group Filtering

Collections support channel scheduling and customer group visibility. To display only collections available to the current browsing context, apply these scopes when building the menu.

use Lunar\Facades\StorefrontSession;

$channel = StorefrontSession::getChannel();
$customerGroups = StorefrontSession::getCustomerGroups();

$rootCollections = Collection::where('collection_group_id', $group->id)
    ->whereIsRoot()
    ->defaultOrder()
    ->channel($channel)
    ->customerGroup($customerGroups)
    ->with(['defaultUrl'])
    ->get();

When filtering by channel or customer group, the cache key should include the channel and customer group IDs to prevent one customer group from seeing another group’s cached menu.

$cacheKey = sprintf(
    'catalog-menu:%s:%s:%s',
    $handle,
    $channel->id,
    $customerGroups->pluck('id')->sort()->implode('-')
);

Putting It All Together

Here is a complete service, view composer, and Blade template for a cached, multi-level catalog menu:

Service

<?php

namespace App\Services;

use Illuminate\Support\Collection as LaravelCollection;
use Illuminate\Support\Facades\Cache;
use Lunar\Models\Collection;
use Lunar\Models\CollectionGroup;

class CatalogMenuService
{
    public function getMenu(string $handle = 'main-menu', int $depth = 3): LaravelCollection
    {
        return Cache::remember(
            "catalog-menu:{$handle}",
            now()->addHour(),
            fn () => $this->buildMenu($handle, $depth)
        );
    }

    public function clearCache(string $handle = 'main-menu'): void
    {
        Cache::forget("catalog-menu:{$handle}");
    }

    protected function buildMenu(string $handle, int $depth): LaravelCollection
    {
        $group = CollectionGroup::where('handle', $handle)->first();

        if (! $group) {
            return collect();
        }

        return Collection::where('collection_group_id', $group->id)
            ->whereIsRoot()
            ->defaultOrder()
            ->with($this->buildEagerLoads($depth))
            ->get();
    }

    protected function buildEagerLoads(int $depth): array
    {
        $eagerLoads = ['defaultUrl'];
        $prefix = '';

        for ($i = 1; $i < $depth; $i++) {
            $prefix .= ($i === 1) ? 'children' : '.children';
            $eagerLoads[$prefix] = fn ($query) => $query->defaultOrder();
            $eagerLoads["{$prefix}.defaultUrl"] = fn ($query) => $query;
        }

        return $eagerLoads;
    }
}

View Composer

<?php

namespace App\Providers;

use App\Services\CatalogMenuService;
use Illuminate\Support\Facades\View;
use Illuminate\Support\ServiceProvider;

class ViewServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        View::composer('layouts.*', function ($view) {
            $view->with(
                'catalogMenu',
                app(CatalogMenuService::class)->getMenu()
            );
        });
    }
}

Blade Template

{{-- resources/views/partials/catalog-menu.blade.php --}}
<nav aria-label="Catalog navigation">
    <ul>
        @foreach($catalogMenu as $rootCollection)
            <li>
                <a
                    href="{{ route('collections.show', $rootCollection->defaultUrl?->slug) }}"
                    @class([
                        'menu-link',
                        'active' => isset($activeCollectionIds) && in_array($rootCollection->id, $activeCollectionIds),
                    ])
                >
                    {{ $rootCollection->attr('name') }}
                </a>

                @if($rootCollection->children->isNotEmpty())
                    <ul>
                        @foreach($rootCollection->children as $child)
                            <li>
                                <a
                                    href="{{ route('collections.show', $child->defaultUrl?->slug) }}"
                                    @class([
                                        'menu-link',
                                        'active' => isset($activeCollectionIds) && in_array($child->id, $activeCollectionIds),
                                    ])
                                >
                                    {{ $child->attr('name') }}
                                </a>

                                @if($child->children->isNotEmpty())
                                    <ul>
                                        @foreach($child->children as $grandchild)
                                            <li>
                                                <a
                                                    href="{{ route('collections.show', $grandchild->defaultUrl?->slug) }}"
                                                    @class([
                                                        'menu-link',
                                                        'active' => isset($activeCollectionIds) && in_array($grandchild->id, $activeCollectionIds),
                                                    ])
                                                >
                                                    {{ $grandchild->attr('name') }}
                                                </a>
                                            </li>
                                        @endforeach
                                    </ul>
                                @endif
                            </li>
                        @endforeach
                    </ul>
                @endif
            </li>
        @endforeach
    </ul>
</nav>

Next Steps

Review the Collections reference for the full list of model fields, relationships, and sort options.
Review the Product Listing Page guide for displaying products when a customer clicks a collection in the menu.
Review the URLs reference for URL generation and slug management.
Review the Channels reference for multi-channel configuration.

Storefront

Customer Account

Overview

How Collections Are Organized

Querying the Menu Data

Fetching a Collection Group

Fetching Root Collections

Fetching Children

Using `descendantsOf` for the Full Tree

Building a Menu Service

Rendering the Menu

Basic Menu Template

Recursive Menu for Unlimited Depth

Active State Tracking

Determining the Active Collection

Applying Active Styles

Caching

Cache the Menu Result

Invalidating the Cache

Multiple Menus

Channel and Customer Group Filtering

Putting It All Together

Service

View Composer

Blade Template

Next Steps

​Overview

​How Collections Are Organized

​Querying the Menu Data

​Fetching a Collection Group

​Fetching Root Collections

​Fetching Children

​Using descendantsOf for the Full Tree

​Building a Menu Service

​Rendering the Menu

​Sharing Menu Data with All Views

​Basic Menu Template

​Recursive Menu for Unlimited Depth

​Active State Tracking

​Determining the Active Collection

​Applying Active Styles

​Caching

​Cache the Menu Result

​Invalidating the Cache

​Multiple Menus

​Channel and Customer Group Filtering

​Putting It All Together

​Service

​View Composer

​Blade Template

​Next Steps

Overview

How Collections Are Organized

Querying the Menu Data

Fetching a Collection Group

Fetching Root Collections

Fetching Children

Using `descendantsOf` for the Full Tree

Building a Menu Service

Rendering the Menu

Sharing Menu Data with All Views

Basic Menu Template

Recursive Menu for Unlimited Depth

Active State Tracking

Determining the Active Collection

Applying Active Styles

Caching

Cache the Menu Result

Invalidating the Cache

Multiple Menus

Channel and Customer Group Filtering

Putting It All Together

Service

View Composer

Blade Template

Next Steps