# Navigation Bar Item

The Navigation Bar Item is a standard item for use within a Navigation Bar. It typically consists of an icon and a label, with different appearances for selected and unselected states.

### Use Cases

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

* **Represent a primary section**
  * Home, Explore, Search, Cart, Orders, Profile, Settings, etc.
* **Give quick, one-tap access**
  * Let users jump directly to important screens from anywhere in the app.
* **Show state of a section**
  * Badge on Cart item (e.g., 3 items)
  * Dot or highlight on Notifications when there’s something new

Each Navigation Bar Item is one “entry point” to a top-level area of the app.

### Core Concepts

1. **Icon + Label = Meaning**
   * The icon gives a quick visual cue.
   * The label clarifies the destination (e.g., “Home”, “Profile”).
   * Together they make navigation **obvious and predictable**.
2. **Active vs Inactive State**
   * One item is in **active/selected** state (current screen).
   * Others are **inactive** but tappable.
   * Visual changes (color, size, underline, or filled icon) indicate which tab is active.
3. **Linked to an Index / Route**
   * Each item maps to a specific **tab index** or **route/screen**.
   * Tapping the item:
     * Updates the active index in the Navigation Bar
     * Switches the displayed screen accordingly
4. **Optional Badges & Indicators**
   * Can show extra info (like unread count, dot, or alert) on a specific item to hint that attention is needed on that section.

### Properties

| Property   | Description                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------ |
| `showIf`   | If `false`, this item will not be displayed in the navigation bar.                                     |
| `onSelect` | An action to perform when this item is selected. This usually involves navigating to a different page. |

#### Label Properties

| Property    | Description                                |
| ----------- | ------------------------------------------ |
| `text`      | The text of the label.                     |
| `textStyle` | The TextStyle for the label.               |
| `alignment` | The alignment of the label.                |
| `maxLines`  | The maximum number of lines for the label. |
| `overflow`  | How label overflow is handled.             |

#### Unselected State Properties

| Property          | Description                                                                     |
| ----------------- | ------------------------------------------------------------------------------- |
| `unselectedType`  | The type of content to display when the item is unselected (`icon` or `image`). |
| `unselectedIcon`  | The icon to display when unselected. See Icon for properties.                   |
| `unselectedImage` | The image to display when unselected. See Image for properties.                 |

#### Selected State Properties

| Property        | Description                                                                   |
| --------------- | ----------------------------------------------------------------------------- |
| `selectedType`  | The type of content to display when the item is selected (`icon` or `image`). |
| `selectedIcon`  | The icon to display when selected. See Icon for properties.                   |
| `selectedImage` | The image to display when selected. See Image for properties.                 |

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

**Use Navigation Bar Item when:**

* You need a standard tab with icon + text label
* Selected/unselected states use different icons or images
* You want automatic state management for active/inactive appearance
* Your design follows typical navigation patterns

**Use Navigation Bar Item Custom when:**

* You need complete layout freedom for the navigation item
* You want to add badges, avatars, or complex widget combinations
* You need custom animations or interactions on tap
* Standard icon + label layout doesn't match your design needs

### Default Properties

The Navigation Bar Item widget does not have standard default properties. Its appearance is controlled by the properties listed above.


---

# 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-item.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.