‹ Toolbar and FAB

Types

Types

The types of toolbar and fab.

SectionToolbar and FABDraftDocumented, not reviewed yet: the API can change.

ToolbarOptions

Type

The toolbar, with buttons that take onPress.

type ToolbarOptions = Omit<OptionsToolbar, 'buttons'> & {
  buttons?: (NavigationButton | OptionsToolbarSpace | OptionsToolbarSearchField)[];
}

Member	Type	Description
testID	string	The identifier tests find the toolbar by.
visible	boolean	Whether the toolbar shows. It applies when the screen appears and on mergeOptions, animated. A toolbar without buttons is always hidden.
buttons	(NavigationButton | OptionsToolbarSpace | OptionsToolbarSearchField)[]

Defined in src/api/options/ScreenOptions.ts ↗

OptionsToolbarSpace

Interface

A space in the buttons of the toolbar. It has no id, text, icon or component, so it is not a button.

interface OptionsToolbarSpace

Member	Type	Description
systemItemRequired	'flexibleSpace' | 'fixedSpace'	'flexibleSpace' takes the free width and pushes the next buttons to the far edge; 'fixedSpace' is a gap of zero width that starts a new capsule with the glass design (iOS 26+).

Defined in src/interfaces/options/toolbar.ts ↗

OptionsToolbarSearchField

Interface

(iOS 26+) The search field of the screen, placed between the buttons of the toolbar. The system puts it there for any topBar.searchBar.placement, even 'stacked'; it needs topBar.searchBar.visible. Before iOS 26 it is skipped and the field is where the placement puts it.

interface OptionsToolbarSearchField

Member	Type	Description
systemItemRequired	'searchField'	Marks the search field.

Defined in src/interfaces/options/toolbar.ts ↗

NavigationFab

Type

The floating action button, and each of its actions, with what its press does.

type NavigationFab = Omit<OptionsFab, 'actions'> & {
  onPress?: ButtonPressHandler;
  actions?: NavigationFab[];
}

Member	Type	Description
iconColor	Color	The tint of the icon. Without it, the onPrimaryContainer of the theme. A merge may set it alone, without a new icon.
idRequired	string	The identifier of the button. A press reports it, and the app finds the onPress of the button by it. A button without an id doesn't show. The same id on a later show or merge updates the button, which stays in place while the screens move; another id replaces it. For an entry of actions it is the id of that entry's own press.
icon	ImageResource	The icon: the name of a drawable resource of the app (for example a Material Symbols icon) or an image source with a uri. It loads in the background and takes the color of iconColor if there is one. A menu without an icon shows a plus; with one, the menu's main button shows it.
testID	string	An identifier for tests and accessibility tools, set on the button (and on the main button of a menu). The scrim of a menu gets <testID>.scrim. Without it, the element has no id. It changes with mergeOptions.
backgroundColor	Color	The color of the button's container. Without it, the primaryContainer of the app's Material 3 theme (the neutral Material 3 theme of the library if the app theme is not Material 3). A { light, dark } pair follows the theme. It does not tint the icon: without iconColor the icon keeps its own colors. A merge with only this key keeps the icon color.
clickColor	Color	The color of the container while the button is pressed. Without it, the color doesn't change and only the ripple shows. It is independent of backgroundColor: setting one keeps the other.
rippleColor	Color	The color of the press ripple. Without it, the one from the theme's style. It stays on a light/dark switch.
visible	boolean	Whether the button shows. false hides it with the Material animation, and closes the actions of a menu; true in a merge shows it again.
alignHorizontally	'left' | 'right'	The side of the row where the button stands. 'right' is the end of the row (the left side in a right-to-left layout), 'left' the start (the right side in a right-to-left layout). A merge applies it.
hideOnScroll	boolean	Whether the button hides after a drag that scrolls the content down and shows after a drag up. Only the vertical lists of the top screen count. A merge applies it; false stops listening.
size	'mini' | 'regular'	The size of the button: 'mini' is 40 dp, 'regular' is 56 dp. It also holds with a Material 3 theme.
scrimColor	Color	The color that dims the screen while the menu's entries are open, one with transparency such as 'rgba(0, 0, 0, 0.32)'. A press on it closes the menu. Without it, nothing is dimmed. A merge applies it from the next opening.
onPress	ButtonPressHandler
actions	NavigationFab[]

Defined in src/api/options/buttons.ts ↗

OptionsFab

Interface

A floating action button over the screen, or an entry of its menu. The button shows while its screen is on top of the stack; without the option there is none. It changes as a push or a pop starts and moves with its screen, as the tab bar does: the new screen's button comes in with it, the old one goes out with the screen it belongs to, and an open menu closes. With an animation of the screens' own the old button shrinks away and the new one grows as it starts; during the back gesture the button of the screen under the top shows with that screen. mergeOptions and the default options of the app apply, and the colors of the theme are read again when the theme changes.

interface OptionsFab

Member	Type	Description
idRequired	string	The identifier of the button. A press reports it, and the app finds the onPress of the button by it. A button without an id doesn't show. The same id on a later show or merge updates the button, which stays in place while the screens move; another id replaces it. For an entry of actions it is the id of that entry's own press.
testID	string	An identifier for tests and accessibility tools, set on the button (and on the main button of a menu). The scrim of a menu gets <testID>.scrim. Without it, the element has no id. It changes with mergeOptions.
backgroundColor	Color	The color of the button's container. Without it, the primaryContainer of the app's Material 3 theme (the neutral Material 3 theme of the library if the app theme is not Material 3). A { light, dark } pair follows the theme. It does not tint the icon: without iconColor the icon keeps its own colors. A merge with only this key keeps the icon color.
clickColor	Color	The color of the container while the button is pressed. Without it, the color doesn't change and only the ripple shows. It is independent of backgroundColor: setting one keeps the other.
rippleColor	Color	The color of the press ripple. Without it, the one from the theme's style. It stays on a light/dark switch.
visible	boolean	Whether the button shows. false hides it with the Material animation, and closes the actions of a menu; true in a merge shows it again.
icon	ImageResource	The icon: the name of a drawable resource of the app (for example a Material Symbols icon) or an image source with a uri. It loads in the background and takes the color of iconColor if there is one. A menu without an icon shows a plus; with one, the menu's main button shows it.
iconColor	Color	The tint of the icon. Without it, the onPrimaryContainer of the theme. A merge may set it alone, without a new icon.
alignHorizontally	'left' | 'right'	The side of the row where the button stands. 'right' is the end of the row (the left side in a right-to-left layout), 'left' the start (the right side in a right-to-left layout). A merge applies it.
hideOnScroll	boolean	Whether the button hides after a drag that scrolls the content down and shows after a drag up. Only the vertical lists of the top screen count. A merge applies it; false stops listening.
size	'mini' | 'regular'	The size of the button: 'mini' is 40 dp, 'regular' is 56 dp. It also holds with a Material 3 theme.
actions	OptionsFab[]	The entries of a menu: the button becomes a menu whose main button opens and closes the entries, each a small button above it. An entry takes id, testID, icon, iconColor, backgroundColor, clickColor, rippleColor and size; its other fields do nothing. Pressing an entry reports its id and closes the menu. A merge with a non-empty list replaces the entries; an empty list takes them away, and the button is a plain button again.
scrimColor	Color	The color that dims the screen while the menu's entries are open, one with transparency such as 'rgba(0, 0, 0, 0.32)'. A press on it closes the menu. Without it, nothing is dimmed. A merge applies it from the next opening.

Defined in src/interfaces/options/stack.ts ↗