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.