# Navigation Bar

The Navigation Bar widget provides a persistent navigation bar at the bottom of the screen, allowing users to switch between different pages or views.

{% embed url="<https://www.youtube.com/watch?v=8Xbq4Pdax9Q>" %}

Watch this on Youtube: <https://www.youtube.com/watch?v=8Xbq4Pdax9Q>

<figure><img src="/files/hgUW90I4NIRAc95lx6rH" alt="A diagram showing the main and cross axis of a Wrap widget."><figcaption><p>Example of a Wrap widget where items wrap to a new line.</p></figcaption></figure>

### Core Concepts

1. **Tabs as Primary Destinations**\
   Each item (icon + label) represents a **top-level screen**, not a sub-page.
   * Example: *Home*, *Search*, *Orders*, *Profile*.
2. **Persistent Across Screens**\
   The Navigation Bar usually stays **visible** while switching between its tabs, giving users a stable mental model of the app’s structure.
3. **Selected vs Unselected State**
   * One item is **selected/active** (current section).
   * Others are **unselected** but tappable.
   * Visual feedback via color, icon change, or label style.
4. **Controlled by an Index / State**
   * Internally, an `activeIndex` (or similar) tells which tab is active.
   * Tapping an item updates this index and switches the visible screen.

### Properties

| Property            | Description                                                   |
| ------------------- | ------------------------------------------------------------- |
| `backgroundColor`   | The background color of the navigation bar.                   |
| `elevation`         | The z-axis elevation of the navigation bar.                   |
| `height`            | The height of the navigation bar.                             |
| `surfaceTintColor`  | The surface tint color of the navigation bar.                 |
| `indicatorColor`    | The color of the indicator that highlights the selected item. |
| `indicatorShape`    | The shape of the indicator (`circle`, `stadium`, etc.).       |
| `overlayColor`      | The color of the overlay that appears when an item is tapped. |
| `showLabels`        | If `true`, labels will be shown for the navigation items.     |
| `animationDuration` | The duration of the animation when switching between items.   |
| `borderRadius`      | The corner radius of the navigation bar.                      |
| `shadow`            | A list of shadow effects to apply to the navigation bar.      |

### Children of Navigation Bar

| Slot       | Description                                                                                     |
| ---------- | ----------------------------------------------------------------------------------------------- |
| `children` | Multiple **Navigation Bar Item** widgets that represent each tab/section in the navigation bar. |

### When to Use Navigation Bar vs Navigation Bar Custom

**Use Navigation Bar when:**

* You need a standard bottom navigation with icon + label items
* Each tab has a simple icon/image and optional text label
* You want built-in selected/unselected state styling
* Your design follows common Material Design patterns

**Use Navigation Bar Custom when:**

* You need complete control over the navigation bar layout
* You want custom shapes, backgrounds, or unique item designs
* You're implementing a floating center button or asymmetrical layout
* Your brand requires highly customized navigation styling

### Default Properties

The Navigation Bar widget supports the following sections of [Default Properties](/ui-building-blocks/widgets/default-properties.md):

**Visibility**

* `visible`

### Use Cases

Use **Navigation Bar** when you want to:

* **Provide app-wide primary navigation**
  * Home, Explore, Cart, Profile, Settings, etc.
  * Quickly jump between 3–5 key sections of the app.
* **Keep core screens always accessible**
  * Make important pages just **one tap away** from anywhere.
  * Reduce back-stack mess (no need to go “back” multiple times to change section).
* **Create a familiar mobile experience**
  * Standard bottom nav like most modern apps (Instagram, YouTube, e-commerce apps).


---

# Agent Instructions: 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:

```
GET https://docs.digia.tech/ui-building-blocks/widgets/navigation-widgets/navigation-bar.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.