Setting the file. One moment.
Megamenu · Storefront Best Practices · medusajs/medusa-agent-skills · Skills Docs
ContentsBack to the top of the page Mcloud
Megamenu is a large, full-width dropdown navigation showing multiple columns of categories, links, and promotional content. Opens from navbar trigger items (e.g., “Shop”, “Men”, “Women”).
Assumed knowledge : AI agents know how to build dropdown menus with hover/click triggers. This focuses on ecommerce megamenu patterns.
Full-width display (spans viewport)
Multiple columns for categories
Positioned directly below navbar
Optional promotional images
Mobile alternative (hamburger menu, not megamenu)
Large product catalog (10+ top-level categories)
Deep hierarchy (parent → child → grandchild levels)
Want to showcase featured products/campaigns
Multiple segments (Men, Women, Kids, etc.)
Visual storytelling needed
Use simple dropdown when:
Small catalog (<10 categories)
Flat category structure (1-2 levels)
Text-only navigation sufficient
Minimalist design preference
Common megamenu triggers:
“Shop” (all categories)
“Men”, “Women”, “Kids” (segmented)
“New Arrivals” (curated)
“Sale” (promotional)
Backend Integration (CRITICAL):
Fetch categories dynamically from ecommerce backend - never hardcode categories. Categories change frequently (new products, seasonal updates, inventory changes). Fetch from API on component mount or during SSR.
Column structure (3-5 columns recommended):
Column 1-3: Category columns
Parent category header (bold, non-clickable or clickable to “View All”)
Child categories below (clickable links)
5-10 links per column maximum
Group related subcategories
Column 4-5: Promotional/Featured
Product image card (1-2 featured products)
Campaign banner (“Summer Sale”, “New Arrivals”)
“Shop the Look” curated sets
Seasonal promotions
Max 5 columns (avoid overcrowding)
Max 10 links per column
1-2 promotional images maximum
Keep height reasonable (<600px)
Common positioning errors that MUST be avoided:
❌ Mistake 1: Navbar doesn’t have position: relative
Without positioning context on navbar, megamenu won’t position correctly
Megamenu will position relative to document body instead of navbar
❌ Mistake 2: Megamenu positioned relative to trigger button
Causes megamenu to appear offset, not aligned to left edge
Megamenu won’t span full width of navbar
Different trigger positions cause inconsistent megamenu placement
❌ Mistake 3: Megamenu doesn’t span full width
Using width: auto or no width constraint
Missing left: 0 and right: 0 properties
Results in narrow dropdown instead of full-width panel
REQUIRED positioning pattern:
Navbar container
MUST have position: relative
Creates positioning context for megamenu
Contains both trigger button and megamenu dropdown
Megamenu dropdown
MUST have position: absolute
MUST have left: 0 (aligns to left edge of navbar)
MUST have right: 0 OR width: 100% (spans full navbar width)
MUST have top: 100% (positioned directly below navbar)
Should have appropriate z-index (above content, below modals)
Content wrapper (inside megamenu)
Use constrained width container (e.g., max-width, container)
Center content with margin: 0 auto
Contains grid/columns for megamenu content
Why this pattern is mandatory:
Navbar position: relative creates positioning context
Megamenu absolute + left: 0 + full width ensures consistent, full-width layout
Positioning relative to navbar (not trigger) prevents offset issues
Inner container centers content while maintaining full-width background
Positioned below navbar (no gap)
White/light background, boxed padding
Shadow or border for depth
High z-index (above page content, below modals)
Equal-width columns or flexible grid
Adequate spacing (24-32px between columns)
Left-aligned text in category columns
Right column(s) for promotional content
Responsive: Stack columns on tablet if needed
Right-aligned (1-2 columns)
Aspect ratio: 2:3 or square
Product images or lifestyle photography
Clickable to product/category page
Include caption or CTA (“Shop Now”)
Desktop hover (recommended):
Megamenu opens on trigger hover
CRITICAL: Megamenu MUST stay open while hovering over the dropdown content
Stays open while hovering trigger OR dropdown area
Closes only when mouse leaves both trigger and dropdown areas
Debounce close (200-300ms delay) to prevent accidental closure
Smooth fade-in/out transition (200-300ms)
If dropdown closes when moving from trigger to content, users can’t access links
Frustrating UX - users can’t interact with megamenu items
Common mistake: Only listening for hover on trigger, not on dropdown
Desktop click (alternative):
Click trigger to toggle open/close
Click outside to close
Better for touch-enabled laptops
Less accidental openings
Hover flickering prevention:
No gap between navbar and dropdown
Dropdown should slightly overlap navbar
Debounce close delay prevents flickering
Do NOT use megamenu on mobile:
Too large for mobile screens
Hard to navigate multi-column layout
Poor touch experience
Mobile alternative (hamburger menu):
Hamburger icon opens slide-in drawer
Vertical accordion for categories
Parent category expands to show children
Simple, scrollable list
See navbar.md for mobile navigation patterns
Megamenu: Desktop only (>1024px)
Hamburger: Tablet and mobile (<1024px)
Not done: Triggered from navbar items (“Shop”, segments)
Not done: CRITICAL: Navbar container has position: relative (creates positioning context)
Not done: CRITICAL: Megamenu has position: absolute with left: 0 (NOT positioned relative to trigger button)
Not done: CRITICAL: Megamenu spans full width (right: 0 or w-full, NOT just w-auto)
Not done: CRITICAL: Megamenu positioned at top: 100% or top-full (directly below navbar)
Not done: Full-width dropdown below navbar, spans entire navbar width
Not done: 3-5 columns for organization
Not done: Category hierarchy (parent → children links)
Not done: Optional promotional images (1-2)
Not done: CRITICAL: Megamenu stays open when hovering over dropdown content (not just trigger)
Not done: Hover trigger with debounced close (200-300ms)
Not done: Smooth fade-in/out transition
Not done: No flickering (no gap between navbar and dropdown)
Not done: Mobile: Use hamburger menu, NOT megamenu
Not done: Keyboard accessible (Tab through links, Escape closes)
Not done: role="navigation" on dropdown panel
Not done: ARIA labels on trigger buttons
Not done: Screen reader friendly (announce expand/collapse)
Not done: Max 10 links per column
Not done: Max 5 columns total
Not done: Fetched dynamically from backend (don’t hardcode categories)
reference/components/megamenu.md