CNTabBar class

A Cupertino-native tab bar: a UITabBar on iOS 26+, and on every macOS an NSSegmentedControl used as tabs (with the .tabs role of macOS 27), each tab showing its symbol and label, centred at its natural width. Below iOS 26 and on other platforms it is a CupertinoTabBar.

On iOS 26+, supports a dedicated search tab: the system search tab at the end of the bar, which reports when search becomes active, so the app can show its search UI (see searchItem).

Example with search:

CNTabBar(
  items: [
    CNTabBarItem(label: 'Home', icon: CNSymbol('house.fill')),
    CNTabBarItem(label: 'Profile', icon: CNSymbol('person.fill')),
  ],
  currentIndex: _index,
  onTap: (i) => setState(() => _index = i),
  searchItem: CNTabBarSearchItem(
    placeholder: 'Find customer',
    onSearchChanged: (query) => filterResults(query),
  ),
)
Inheritance
Available extensions

Constructors

CNTabBar({Key? key, required List<CNTabBarItem> items, required int currentIndex, required ValueChanged<int> onTap, Color? tint, Color? backgroundColor, double? iconSize, double? height, bool split = false, int rightCount = 1, bool shrinkCentered = true, double splitSpacing = 12.0, CNTabBarSearchItem? searchItem, CNTabBarSearchController? searchController, String? labelFontFamily, double? labelFontSize, FontWeight? labelFontWeight, FontWeight? selectedLabelFontWeight, TextDirection? textDirection, bool autoHideOnModal = true, bool autoHideOnPageTransition = true, void onMenuSelected(int index, List<int> path)?})
Creates a Cupertino-native tab bar.
const

Properties

autoHideOnModal → bool
Whether the tab bar automatically hides itself while a modal/sheet is presented over its route.
final
autoHideOnPageTransition → bool
Whether the tab bar's platform view is hidden from Flutter's scene while the enclosing route is animating in or out (e.g. during a CupertinoPageRoute push or pop). Default: true.
final
backgroundColor → Color?
Background color for the bar.
final
currentIndex → int
The index of the currently selected item.
final
hashCode → int
The hash code for this object.
no setterinherited
height → double?
Fixed height; if null uses intrinsic height reported by native view.
final
iconSize → double?
Default icon size when item icon does not specify one.
final
items → List<CNTabBarItem>
Items to display in the tab bar.
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
labelFontFamily → String?
Optional custom font family for tab bar item labels.
final
labelFontSize → double?
Optional font size for tab bar item labels.
final
labelFontWeight → FontWeight?
The weight of the labels of the tabs that are not selected. Null keeps the system's medium (with labelFontFamily, the family's nearest face).
final
onMenuSelected → void Function(int index, List<int> path)?
Called when an entry is chosen in the menu of an item with CNTabBarItem.menuItems: index is the item, path the entry, as in CNPopupMenuButton.onPathSelected.
final
onTap → ValueChanged<int>
Called when the user selects a new item.
final
rightCount → int
How many trailing items to pin right when split is true.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
searchController → CNTabBarSearchController?
Optional controller for programmatic search management.
final
searchItem → CNTabBarSearchItem?
Optional search tab configuration.
final
selectedLabelFontWeight → FontWeight?
The weight of the selected tab's label. Null keeps the system's semibold, so the selected tab stands out as on the system bar.
final
shrinkCentered → bool
When true, centers the split groups more tightly.
final
split → bool
When true, splits items between left and right sections.
final
splitSpacing → double
Gap between left/right halves when split.
final
textDirection → TextDirection?
The direction the native bar lays its tabs out in: the first tab on the right for TextDirection.rtl, with its badges, menus and split halves mirrored. Null takes the ambient Directionality, so an app that switches to Arabic in Dart gets a right-to-left native bar as it gets a right-to-left fallback bar (#142).
final
tint → Color?
Accent/tint color.
final

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<CNTabBar>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
liquidGlass({CNGlassEffect effect = CNGlassEffect.regular, CNGlassEffectShape shape = CNGlassEffectShape.capsule, double? cornerRadius, Color? tint, bool interactive = false}) → Widget

Available on Widget, provided by the LiquidGlassExtension extension

Applies a Liquid Glass effect to this widget.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

precacheIcons(List<CNTabBarItem> items, {double? iconSize}) → Future<void>
Renders the custom icons of items ahead of the bar's first mount.