Options
The options of bar buttons.
Options
Every key, with the platforms it works on. A dashed platform means the key does nothing there.
20 options shown
The buttons at the leading edge, the first at the edge. The list is replaced as a whole and [] removes the buttons; they take nothing from the lists of the default options or the stack. They replace the back button on both platforms; on Android a first button with an id also removes the arrow. mergeOptions animates the change with animateLeftButtons.
The buttons at the trailing edge, the first at the edge. The list is replaced as a whole. When space runs out iOS first removes the title, then moves right buttons to the overflow; on Android the bar keeps the buttons of the highest priority, and the rest go to the overflow menu.
(iOS 16+) The buttons in the middle of the bar, in the format of the side buttons. A button, or neighbors with the same group, is one group (one capsule). They show in the middle only on iPad with a style of 'browser' or 'editor'; on iPhone, in 'navigator' and while the tab bar of iPad sits in the bar they are in the overflow menu, a section per group, where an icon button needs a text. Toggles and menus of center buttons keep their state.
The overflow menu ("•••" on iOS 16+, the vertical dots on Android): its items come above the buttons the platform moved there, and the overflow button always shows with them. A pick sends a button press with its id. items: [] removes the items. On iOS the menu is built from the options at each opening, and a title is the title of its section; before iOS 16 there is none. On Android the items come first, always in the menu, with icons, destructive and disabled states, checks and submenus, and the overflow takes the place of one button, so the buttons are laid out again.
The identifier tests find the overflow button by. On Android it is the view of the dots; on iOS the system draws the "•••" button, so it may not carry the identifier.
The title above the items. (iOS) Android doesn't show it.
Whether only one item of the top level can be checked at a time: picking an item moves the check mark to it. On iOS this is the system's single-selection menu; on Android the items are checkable.
The items and submenus, in order. An empty list removes the menu.
(iOS 27.1+) Who keeps the space in the vertical bar of iPhone Duo, where tabs and the buttons of the screen share it: 'tabs' keeps the tabs and moves the buttons to the overflow, 'buttons' keeps the buttons and compresses the tabs. Without it the system keeps the tabs. For a pair of screens the option of the primary one counts.
(iOS 16+) Lets the user customize the center buttons on iPad and Mac, under this name; the system saves the choice. A group is customizable by its group name (several buttons) or by the id of the button; one without a name, or with a taken one, is fixed. The panel opens from the system menu of iPadOS 26 (View, Customize Toolbar). Empty means no customization, always on iPhone. The list of buttons in the options doesn't change and no callback comes.
The color of the left buttons that have no color of their own. Without it, the tint of the bar on iOS, the theme's text color on Android with icons untinted. The buttons get copies with the color, so a color doesn't stay in buttons shared with other screens. mergeOptions repaints the shown buttons and keeps the color in the screen's own buttons through the next appearance and a theme switch. On iOS it sets the text color and the tint; an SF Symbol without a color is drawn as a template, disableIconTint keeps its colors.
The same for the right buttons, including pinned ones on iOS. On Android it also colors the overflow icon (the theme's on-surface-variant color without it).
The shape color behind the icons of the left buttons that have an icon image and no iconBackground.color; the size and corners come from the button's iconBackground, or the icon's size without corners. On iOS only image buttons, not SF Symbols, and without a capsule with the glass design. A color sent by mergeOptions repaints all the side's image buttons, those with their own shape color too.
The same for the right buttons.
The color of the disabled left buttons that have no disabledColor of their own. On iOS the text color and the tint of the icon (without it the system dims them); on Android the text and icon tint, light gray by default.
The same for the right buttons.
(iOS 16+) The color of the center buttons that have no color of their own, handled like leftButtonColor.
(iOS 16+) The color of the disabled center buttons that have no disabledColor of their own.
Whether a change of the left buttons of the shown screen is animated: on iOS the new buttons fade in, but a side with a group of several buttons changes at once; on Android it is a transition of the left bar. On iOS 26 and later the system cross-fades a change of the bar's buttons by itself, also when this is false.
Whether a change of the right buttons of the shown screen is animated, like animateLeftButtons.