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.

Example of a Wrap widget where items wrap to a new line.

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:

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