# Header mega-menus (/themes/mega-menus)

A mega-menu is a **Dropdown panel** (`mega-panel`) block inside the header's **Menu** block
(`menu`). Each panel binds to one top-level link of the menu the block shows, by the link's
`id`, and that link opens the panel instead of its plain dropdown. The binding follows the link
when the menu is reordered. A link set to **Show items directly in the bar** opens no panel. A
panel whose link was deleted stays in the navigator, unbound, until you pick another link.

In the Customizer, select the menu in the header and add a **Dropdown panel** to it. Pick the
**Menu item** it opens under, then build its content from any blocks:

- layout blocks (stack, grid, columns) to arrange columns;
- `link-list` for a column of links from a menu, a category or your own list;
- `link-card` for an image with a title and a link;
- `product` and `product-grid` (a category source works well) for products;
- text blocks such as `heading` and `text`.

A new panel starts from the **Two columns and a card** preset. Its **Width** is **Content** (the
page's content width) or **Full** (the full width of the header). While a panel or anything
inside it is selected, the canvas holds it open. The navigator lists panels under their menu
block.

A menu block in a header layout file, with one panel:

```json
{
  "id": "menu-1",
  "type": "menu",
  "settings": { "menu": "primary", "submenu": "mega", "open_on": "hover" },
  "blocks": [
    {
      "id": "mega-panel-1",
      "type": "mega-panel",
      "settings": { "item": "link-k3v9qa", "width": "full" },
      "blocks": [
        {
          "id": "link-list-1",
          "type": "link-list",
          "settings": { "menu": "primary", "heading": "Shop" }
        },
        {
          "id": "link-card-1",
          "type": "link-card",
          "settings": { "title": "New arrivals", "link": "/products" }
        }
      ]
    }
  ]
}
```

Items without a panel keep their dropdown of child links. The menu block's **Submenu** setting
draws those as a compact dropdown or as a wide panel of links.

## Opening behaviour [#opening-behaviour]

The menu block's **Opens on** sets how its dropdowns open on desktop. A menu item can override
it with its own **Open on desktop** in the Menus editor:

- **Hover** opens the item when the pointer enters it.
- **Click** opens the item when its button is activated.

Mobile menus always expand on tap, as accordions. The opening behaviour is shared by every
language. In theme code, each `MenuLink` from `@poltura/theme-sdk/navigation` carries it as
`opens` (`null` follows the menu's setting), and `MainNav` follows it. The stored link looks
like this:

```json
{ "id": "link-k3v9qa", "label": "Shop", "href": "/products", "open": "click", "children": [] }
```

Every stored menu link has an `id`. A link saved without one, by the Menus editor, the AI
assistant or a theme file, gets one when it is saved.

Omit `open` to inherit the menu's setting. Items displayed directly in the header bar have no
dropdown to open.

The header mega-menu is separate from the default theme's home page section called "Mega
menu". That section draws its blocks with `<Slot />`: a `menu_groups` block lists a column for
every item of the primary menu or every top category, `menu_column` blocks add columns of their
own links, and `promo_card` blocks add offers. Merchants reorder, restyle or hide each of them.
See [Sections, blocks and element styles](/themes/elements).

## Keyboard access [#keyboard-access]

Header menus use disclosure navigation rather than trapping focus:

- **Tab / Shift+Tab** follow the normal page order, including visible dropdown links.
- **Down / Up** on a menu trigger open it and focus its first / last link.
- **Left / Right** move between adjacent header items; **Home / End** select the first / last.
- Within a dropdown, **Down / Up** move between its links; **Home / End** select its endpoints.
- **Escape** closes the dropdown and restores focus to its trigger.
- **Enter / Space** activate click-mode buttons. Hover-mode links keep their Enter navigation;
  **Space** toggles their dropdown.

Opening another dropdown closes the previous one. Keyboard focus stays visible in the theme's
focus colour, and pointer movement does not close a dropdown while its links hold keyboard focus.

## Next [#next]

- [Chat widget chrome](/themes/chat-widget): arrange the chat launcher and panel in theme code.
- [navigation reference](/themes/sdk/reference/navigation): `MainNav`, `MegaMenu`, `useMenu`
  and the other navigation parts.