> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/dynamic-components/components/navigation-container.md).
# Navigation Container
The Navigation Container combines a navigation menu — horizontal, vertical, or dropdown — with a content area that shows a different slot for each menu item. Drop any Avonni components into those areas to build layouts where users switch between sections using the menu. Use it for multi-section record pages, wizards, filtered dashboards, or any layout where you want one region of the page to change based on the selected navigation item.
## Overview
{% hint style="warning" %}
#### Key Difference with the Vertical Navigation Component
The Navigation Container and the [Vertical Navigation component](/dynamic-components/components/vertical-navigation.md) look similar but serve very different purposes.
* **Vertical Navigation** is a **data-driven** component. You connect it to a data source (records, picklist, or manual list), and it renders one navigation item per record. You **cannot drag other Avonni components inside the items** — it is a navigation element, not a layout.
* **Navigation Container** is a **layout container**. You define the navigation items manually, and then drag any Avonni components into the content area of each item. You control the layout and content of every item independently.
Use **Vertical Navigation** when the navigation items come from a list of records. Use the **Navigation Container** when you want to build a menu-based layout with arbitrary components inside each section.
{% endhint %}
### Quick Start: Build an Account Detail Menu in 2 Minutes
Follow these steps to add a horizontal navigation to an Account Record Page with three sections: **Overview**, **Contacts**, and **Files**.
{% stepper %}
{% step %}
#### **Create a New Component**
* Open the **Avonni Dynamic Components** App.
* Click **New**.
* **Name:** Enter a name (e.g., "Account Navigation Layout").
* **Target Page Object:** Select **Account**.
* *Why: This lets variables like `{!RecordId}` resolve to the Account currently being viewed.*
{% endstep %}
{% step %}
#### **Add the Component to the Canvas**
* From the **Component Library** (left sidebar), search for **Navigation Container**.
* Drag it onto the canvas.
{% endstep %}
{% step %}
#### **Define the Navigation Items**
* Select the Navigation Container on the canvas.
* In the Properties Panel (right), find **Items** and click the button to open the Items editor.
* Click **Add Item** three times and configure each:
* **Item 1** — Label: `Overview`, Value: `overview`, Icon Name: `standard:account`.
* **Item 2** — Label: `Contacts`, Value: `contacts`, Icon Name: `standard:contact`.
* **Item 3** — Label: `Files`, Value: `files`, Icon Name: `standard:file`.
* *Why: The **Value** must be unique. It is what you reference when setting the default active item or reacting to item clicks.*
{% endstep %}
{% step %}
#### **Choose a Variant**
* Still in the Properties Panel, set **Variant** to **Horizontal**.
* *Note: Use **Vertical** for a sidebar-style menu, or **Dropdown** to collapse all items into a single button.*
* Set **Active Item Value** to `overview` so the first section is selected by default when the page loads
{% endstep %}
{% step %}
#### **Add Content to Each Navigation Item**
This is the step that distinguishes this component from Vertical Navigation.
* On the canvas, click the **Overview** item in the menu preview — the content area below activates.
* Drag a **Record Detail** component into that area.
* Click the **Contacts** item to switch the canvas to that item's content area.
* Drag a **Data Table** component into it, then connect it to a `Contact` query filtered by `AccountId = {!RecordId}`.
* Click the **Files** item and drop a **File Upload** component into its area.
* *Why: Each navigation item is an independent container. Whatever you drop inside only appears when that item is selected.*
{% endstep %}
{% step %}
#### **Save and Activate**
* Click **Save**.
* Click **Activate** to [add this dynamic component to your Account Lightning Page](/dynamic-components/core-concepts/publishing-your-dynamic-components.md).
{% endstep %}
{% endstepper %}
### Example: Service Console Case Page with Tabbed Workspace
**Scenario:** Provide service agents with a compact, vertical navigation on the left side of a Case record page, featuring three workspaces: **Case Details**, **Customer History**, and **Related Articles**.
{% stepper %}
{% step %}
#### **Create the Component**
* Open the **Avonni Dynamic Components** App.
* Click **New**.
* **Name:** `Case Agent Workspace`.
* **Target Page Object:** Select **Case**.
{% endstep %}
{% step %}
#### **Add the Navigation Container**
* Drag the Navigation Container onto the canvas.
* In the Properties Panel, set **Variant** to **Vertical**.
* Set **Shaded** to `true` to separate the sidebar visually from the content.
{% endstep %}
{% step %}
#### **Build the Navigation Items**
Open the **Items** editor and add three items:
* **Case Details** — Value: `details`, Icon: `standard:case`.
* **Customer History** — Value: `history`, Icon: `standard:account`.
* **Related Articles** — Value: `articles`, Icon: `standard:knowledge`.
Set **Active Item Value** to `details`.
{% endstep %}
{% step %}
#### **Populate Each Item's Content**
* Click **Case Details** on the canvas and drop a **Record Detail** component inside, bound to `{!RecordId}`.
* Click **Customer History** and drop a **Data Table** querying prior `Case` records for the account (`AccountId = {!Case.AccountId}`).
* Click **Related Articles** and drop a **List** component querying `KnowledgeArticleVersion` filtered to the Case's topic.
{% endstep %}
{% step %}
#### **Log Navigation Clicks for Analytics**
* Open the **Interactions** tab.
* Add an **Item Click** interaction with the **Execute Flow** action.
* Select an Autolaunched Flow that writes a record to a custom `Workspace_Usage__c` object, mapping the clicked item's **Value** as the Flow input.
{% endstep %}
{% step %}
#### **Save and Activate**
Save the component and activate it to the Case Record Page. The agent now has a compact workspace that lets them switch sections without scrolling.
{% endstep %}
{% endstepper %}
### Key Considerations
* **Plan your navigation depth first.** Decide how many sections you need before building. Adding a fourth item later means rebuilding layout spacing, especially in Horizontal variant.
* **Keep item values stable.** If you rename a Value after binding it to Active Item Value, filters, or Flow mappings, those references break. Treat Value as an API name.
* **Use Vertical for dense layouts, Horizontal for scannable layouts, Dropdown for mobile or space-constrained pages.** The variant affects not only look but also how many items comfortably fit.
* **Combine with component visibility rules** to render sections conditionally based on user, record status, or permissions — without creating multiple Lightning Pages.
* **Performance:** Every component you drop inside a navigation item loads when the page loads, not when the item is first clicked. For heavy components (large data tables, charts), consider how many you place across all items.
* **Nested containers are allowed.** You can place Containers, Columns, Tabbed Containers, or even another Navigation Container inside a navigation item for more complex layouts
## Configuration
To configure the Navigation Container, select it on the canvas. The **Edit Navigation Container** panel opens on the right with three tabs: **Properties**, **Interactions**, and **Style**. The sections below mirror the Properties tab.
### Navigation Items
The **Items** setting defines the entries that appear in the navigation. Each item has its own content area for child components.
| Setting | Description |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Label** | The text label displayed on the navigation item. |
| **Value** | A unique identifier for the item. Required. Used by **Active Item Value** and by any interaction that reacts to the clicked item. |
| **Icon Name** | The Lightning Design System icon displayed to the left of the label (e.g., `standard:account`, `utility:user`). |
| **Disabled** | If enabled, the item is grayed out and users cannot interact with it. |
| **Hidden** | If enabled, the item is hidden from the navigation. Useful for conditionally removing sections based on a Boolean expression. |
{% hint style="warning" %}
#### **The content area is empty until you fill it**
Adding items only creates the navigation entries. The content panel below each item stays blank until you drag Avonni components into it on the canvas.
{% endhint %}
The **Active Item Value** setting defines which item is selected when the component loads. Set it to the **Value** of one of your items. Requires **Items** to be configured first.
* **Static default:** Type the value directly (e.g., `overview`). That item opens by default every time.
* **Dynamic default:** Bind it to a Variable, URL parameter, or record field to change the active item at runtime.
### Variant and Display Settings
These settings control how the navigation looks and behaves.
| Setting | Description | Options |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Variant** | How the navigation renders. | **Horizontal** (default) — items in a row above the content. **Vertical** — items in a sidebar. **Dropdown** — all items collapsed into a single dropdown button. |
| **Shaded** | Adds a shaded background to the navigation items for more visual separation. Requires **Variant** = **Horizontal** or **Vertical**. | true / false (Default: off) |
| **Open Menu On Hover** | Allows sub-item menus to open when the mouse hovers over a parent item. Requires **Variant** = **Horizontal** or **Dropdown**. | true / false (Default: off) |
### Title
The **Title** section (collapsible in the Properties Panel) adds an optional header above the navigation, useful when the component acts as a standalone sidebar or panel.
| Setting | Description |
| ---------------- | --------------------------------------------------------------------------------------------------------------- |
| **Title** | Text displayed as the header. Supports expressions for dynamic content. |
| **Icon Name** | The Lightning Design System icon shown next to the title. |
| **Icon Size** | Size of the title icon. Options: Xxs, Xs, Small, **Medium** (default), Large. Requires **Icon Name** to be set. |
| **Image Source** | URL of an image to show in place of the title icon. The image takes priority over the icon. |
### Item Indicator
A visual marker (a line) indicates which item is currently active. This section is only available when **Variant** is **Horizontal** or **Vertical**.
| Setting | Description |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Show** | Displays the active-item indicator. (Default: on) |
| **Position** | Where the indicator appears relative to the item. **Top (horizontal) / Left (vertical)** (default), or **Bottom (horizontal) / Right (vertical)**. Requires **Show** to be enabled. |
### Set Component Visibility
All components support conditional visibility — see [Component Visibility](/dynamic-components/core-concepts/component-visibility.md).
## Interactions
[Interactions](/dynamic-components/component-builder/interactions.md) define what happens when users interact with the Navigation Container. Configure them from the **Interactions** tab of the Edit Navigation Container panel.
### Item Click
Fires when a user clicks a navigation item that is not already active. Use the **activeItem** and **activeItemValue** output variables to identify which item was selected and drive downstream logic such as executing a Flow, navigating to a record, or logging the interaction.
## Output Variables
The Navigation Container exposes these output variables you can reference elsewhere on the page after the user interacts with it.
### Item Selection
Updates when a user clicks a navigation item.
| Output variable | Type | What it returns |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------ |
| **Active Item** | Object | The full item object currently active — its label, value, icon name, disabled state, and hidden state. |
> **Example:** When a user clicks the "Contacts" item, use **Active Item** to display a contextual header in a nearby Text component showing which section is currently open.
## Troubleshooting Common Issues
* **Content area is blank after selecting a navigation item** — Each item is an empty container until you place components inside. Select the container on the canvas, click the specific navigation item, then drag Avonni components from the Component Library into that item's content area.
* **No navigation items appear** — The Items collection is empty, or every item has Hidden set to `true`. Open the Items editor and add at least one item with Hidden unchecked.
* **Page loads with no item selected** — Active Item Value is blank or does not match any item's Value exactly. Set Active Item Value to one of the item Value strings — matching is case-sensitive and must be an exact match.
* **Shaded has no effect** — The Variant is set to Dropdown. The Shaded option only applies to Horizontal and Vertical variants. Switch to Horizontal or Vertical, or accept the default appearance for Dropdown.
* **Open Menu on Hover is missing from the Properties Panel** — The Variant is set to Vertical. Hover behavior is only available for Horizontal and Dropdown variants. Switch to Horizontal or Dropdown if you need hover-to-open behavior.
* **Item indicator line does not show** — Show is unchecked in the Item Indicator section, or the Variant is Dropdown where the indicator does not apply. Expand the Item Indicator section and check Show. For Dropdown navigations, the indicator is intentionally unavailable.
* **Title icon does not appear even though Icon Name is set** — Image Source is also set, and the image takes priority over the icon. Clear the Image Source field, or remove the icon if you meant to use the image.
* **Clicking a navigation item switches the content but the interaction does not fire** — No Item Click interaction is configured, or the configured action is missing required field mappings. Open the Interactions tab, add an Item Click trigger, and complete the action's mappings.
* **An item should be conditionally hidden but always shows** — Hidden is a static `false`, or the Boolean expression bound to it evaluates to `false`. Bind Hidden to a Boolean expression (e.g., `{!User.Profile.Name == 'Standard User'}`) and test it in the Debug Panel using Preview Context.
* **Component works in preview but not on the Lightning Page** — The component was saved but not deployed, or the Target Page Object does not match the page's object. Click Deploy, then confirm the component's Target Page Object matches the Lightning Page's record object.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.avonnicomponents.com/dynamic-components/components/navigation-container.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.