BottomNavigationBar class

A material widget that's displayed at the bottom of an app for selecting among a small number of views, typically between three and five.

There is an updated version of this component, NavigationBar, that's preferred for new applications and applications that are configured for Material 3 (see ThemeData.useMaterial3).

The bottom navigation bar consists of multiple items in the form of text labels, icons, or both, laid out on top of a piece of material. It provides quick navigation between the top-level views of an app. For larger screens, side navigation may be a better fit.

A bottom navigation bar is usually used in conjunction with a Scaffold, where it is provided as the Scaffold.bottomNavigationBar argument.

The bottom navigation bar's type changes how its items are displayed. If not specified, then it's automatically set to BottomNavigationBarType.fixed when there are less than four items, and BottomNavigationBarType.shifting otherwise.

The length of items must be at least two and each item's icon and label must not be null.

BottomNavigationBarType.fixed, the default when there are less than four items. The selected item is rendered with the selectedItemColor if it's non-null, otherwise the theme's ColorScheme.primary color is used for Brightness.light themes and ColorScheme.secondary for Brightness.dark themes. If backgroundColor is null, The navigation bar's background color defaults to the Material background color, ThemeData.canvasColor (essentially opaque white).
BottomNavigationBarType.shifting, the default when there are four or more items. If selectedItemColor is null, all items are rendered in white. The navigation bar's background color is the same as the BottomNavigationBarItem.backgroundColor of the selected item. In this case it's assumed that each item will have a different background color and that background color will contrast well with white.

Updating to NavigationBar

The NavigationBar widget's visuals are a little bit different, see the Material 3 spec at m3.material.io/components/navigation-bar/overview for more details.

The NavigationBar widget's API is also slightly different. To update from BottomNavigationBar to NavigationBar, you will need to make the following changes.

Instead of using BottomNavigationBar.items, which takes a list of BottomNavigationBarItems, use NavigationBar.destinations, which takes a list of widgets. Usually, you use a list of NavigationDestination widgets. Just like BottomNavigationBarItems, NavigationDestinations have a label and icon field.
Instead of using BottomNavigationBar.onTap, use NavigationBar.onDestinationSelected, which is also a callback that is called when the user taps on a navigation bar item.
Instead of using BottomNavigationBar.currentIndex, use NavigationBar.selectedIndex, which is also an integer that represents the index of the selected destination.
You may also need to make changes to the styling of the NavigationBar, see the properties in the NavigationBar constructor for more details.

Using BottomNavigationBar

This example shows a BottomNavigationBar as it is used within a Scaffold widget. The BottomNavigationBar has three BottomNavigationBarItem widgets, which means it defaults to BottomNavigationBarType.fixed, and the currentIndex is set to index 0. The selected item is amber. The _onItemTapped function changes the selected item's index and displays a corresponding message in the center of the Scaffold.

To create a local project with this code sample, run:
flutter create --sample=material.BottomNavigationBar.1 mysample

This example shows how you would migrate the above BottomNavigationBar to the new NavigationBar.

To create a local project with this code sample, run:
flutter create --sample=material.BottomNavigationBar.2 mysample

This example shows a BottomNavigationBar as it is used within a Scaffold widget. The BottomNavigationBar has four