# 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="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-e3022123c9bb8695cb6bab78e4ff07a2a8f04444%2Fnav_bar.png?alt=media" 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](https://docs.digia.tech/ui-building-blocks/widgets/default-properties "mention"):

**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).