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