This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 54).

Expo Router Toolbar

An Expo Router submodule that provides native toolbar components.

iOS

GitHub

npm

Changelog

Toolbar is currently in alpha and available in canary releases of expo-router. Using the toolbar together with tabs is not supported at the moment.

expo-router/unstable-toolbar is a submodule of expo-router and exports components to add a native toolbar to your app.

See the Expo Router reference for more information about the file-based routing library for native and web app.

Installation

To use expo-router/unstable-toolbar in your project, you need to install expo-router in your project. Follow the instructions from Expo Router's installation guide:

Install Expo Router

Learn how to install Expo Router in your project.

API

import { Toolbar } from 'expo-router/unstable-toolbar';

Components

`Toolbar`

iOS

Type: React.Element<ToolbarProps>

A component that provides a bottom toolbar.

Example

import { Toolbar } from "expo-router";

export default function MyScreen() {
  return (
    <>
      <YourScreenContent />
      <Toolbar>
        <Toolbar.Spacer />
        <Toolbar.Button icon="magnifyingglass" tintColor={Color.ios.placeholderText} />
        <Toolbar.View>
          <TextInput style={{ width: 200 }} placeholder="Search" />
        </Toolbar.View>
        <Toolbar.Menu icon="ellipsis">
          <Toolbar.MenuAction icon="mail" title="Send email" onPress={() => {}} />
          <Toolbar.MenuAction icon="trash" title="Delete" destructive onPress={() => {}} />
        </Toolbar.Menu>
        <Toolbar.Spacer />
      </Toolbar>
    </>
  );
}

ToolbarProps

`children`

iOS

Optional • Type: ReactNode

`ToolbarMenu`

iOS

Type: React.Element<React.FC<ToolbarMenuProps>>

Adds a context menu for to a toolbar.

Example

<Toolbar>
  <Toolbar.Menu title="Options">
    <Toolbar.MenuAction title="Action 1" onPress={() => {}} />
    <Toolbar.MenuAction title="Action 2" onPress={() => {}} />
  </Toolbar.Menu>
</Toolbar>

ToolbarMenuProps

`accessibilityHint`

iOS

Optional • Type: string

`accessibilityLabel`

iOS

Optional • Type: string

`children`

iOS

Optional • Type: ReactNode

`destructive`

iOS

Optional • Type: boolean

If true, the menu item will be displayed as destructive.

See: Apple documentation for more information.

`disabled`

iOS

Optional • Type: boolean

`elementSize`

iOS 16.0+

Optional • Literal type: string

The preferred size of the menu elements. elementSize property is ignored when palette is used.

See: Apple documentation for more information.

Acceptable values are: 'small' | 'medium' | 'auto' | 'large'

`hidden`

iOS

Optional • Type: boolean

`hidesSharedBackground`

iOS 26+

Optional • Type: boolean

Whether to hide the shared background when sharesBackground is enabled.

Only available for root level menus.

See: Official Apple documentation for more information.

`icon`

iOS

Optional • Type: SFSymbols6_0

Optional SF Symbol displayed alongside the menu item.

`inline`

iOS

Optional • Type: boolean

If true, the menu will be displayed inline. This means that the menu will not be collapsed

*Note: Inline menus are only supported in submenus.

See: Apple documentation for more information.

`palette`

iOS

Optional • Type: boolean

If true, the menu will be displayed as a palette. This means that the menu will be displayed as one row. The elementSize property is ignored when palette is used, all items will be elementSize="small". Use elementSize="medium" instead of palette to display actions with titles horizontally.

Note: Palette menus are only supported in submenus.

See: Apple documentation for more information.

`separateBackground`

iOS 26+

Optional • Type: boolean • Default: false

Whether to separate the background of this item from other header items.

Note: Text buttons cannot share the background.

This prop reverses the native behavior of sharesBackground.

See: Official Apple documentation for more information.

`style`

iOS

Optional • Type: StyleProp<BasicTextStyle>

Style for the label of the header item.

`subtitle`

iOS

Optional • Type: string

An optional subtitle for the menu. Does not appear on inline menus.

See: Apple documentation for more information.

`tintColor`

iOS

Optional • Type: ColorValue

Tint color for the menu icon and text.

`title`

iOS

Optional • Type: string

The title of the menu item

`variant`

iOS

Optional • Literal type: string • Default: 'plain'

Controls the visual style of the menu when represented as a bar button.

Acceptable values are: 'done' | 'plain' | 'prominent'

`ToolbarMenuAction`

iOS

Type: React.Element<LinkMenuActionProps>

A single action item within a toolbar menu.

For available props, see LinkMenuActionProps.

Example

<Toolbar>
  <Toolbar.Menu title="Options">
    <Toolbar.MenuAction title="Action 1" onPress={() => {}} />
    <Toolbar.MenuAction title="Action 2" onPress={() => {}} />
  </Toolbar.Menu>
</Toolbar>

`ToolbarButton`

iOS

Type: React.Element<ToolbarButtonProps>

A button component for use in the toolbar. It should only be used as a child of Toolbar.

Example

<Toolbar>
  <Toolbar.Button icon="magnifyingglass" tintColor={Color.ios.placeholderText} />
  <Toolbar.Button>Text Button</Toolbar.Button>
  <Toolbar.Button hidden={!isSearchFocused} icon="xmark" onPress={handleClear} />
</Toolbar>

ToolbarButtonProps

`accessibilityHint`

iOS

Optional • Type: string

`accessibilityLabel`

iOS

Optional • Type: string

`children`

iOS

Optional • Type: ReactNode

The text label for the button.

Note: When icon is used, the label will not be shown and will be used for accessibility purposes only.

Example

import { Toolbar } from 'expo-router/unstable-toolbar';

...
<Toolbar.Button>This is button label</Toolbar.Button>

`disabled`

iOS

Optional • Type: boolean

`hidden`

iOS

Optional • Type: boolean • Default: false

Whether the button should be hidden.

`hidesSharedBackground`

iOS 26+

Optional • Type: boolean

Whether to hide the shared background.

See: Official Apple documentation for more information.

`icon`

iOS

Optional • Type: SFSymbols6_0

The name of the SF Symbol to display as the button icon. For a list of available symbols, see SF Symbols.

`onPress`

iOS

Optional • Type: () => void

Callback function when the button is pressed.

`possibleTitles`

iOS

Optional • Type: string[]

See: Official Apple documentation for more information.

`selected`

iOS

Optional • Type: boolean

Whether the button is in a selected state

See: Official Apple documentation for more information.

`separateBackground`

iOS 26+

Optional • Type: boolean • Default: false

Whether to separate the background of this item from other header items.

Note: Text buttons cannot share the background.

This prop reverses the native behavior of sharesBackground.

See: Official Apple documentation for more information.

`style`

iOS

Optional • Type: StyleProp<BasicTextStyle>

Style for the label of the header item.

`tintColor`

iOS

Optional • Type: ColorValue

Tint color for the button icon and text.

`variant`

iOS

Optional • Literal type: string • Default: 'plain'

See: Official Apple documentation for more information.

Acceptable values are: 'done' | 'plain' | 'prominent'

`ToolbarSpacer`

iOS

Type: React.Element<ToolbarSpacerProps>

A spacer component for the toolbar. Without a width, it creates a flexible spacer that expands to fill available space. With a width, it creates a fixed-width spacer. It should only be used as a child of Toolbar.

Example

<Toolbar>
  <Toolbar.Spacer />
  <Toolbar.Button icon="magnifyingglass" />
  <Toolbar.Spacer width={20} />
  <Toolbar.Button icon="mic" />
  <Toolbar.Spacer />
</Toolbar>

ToolbarSpacerProps

`hidden`

iOS

Optional • Type: boolean • Default: false

Whether the spacer should be hidden.

`hidesSharedBackground`

iOS 26+

Optional • Type: boolean

Whether to hide the shared background when sharesBackground is enabled.

See: Official Apple documentation for more information.

`sharesBackground`

iOS 26+

Optional • Type: boolean • Default: false

Whether the spacer shares the background with adjacent toolbar items.

See: Official Apple documentation for more information.

`width`

iOS

Optional • Type: number

By default, the spacer is flexible and expands to fill available space. If a width is provided, it creates a fixed-width spacer.

`ToolbarView`

iOS

Type: React.Element<ToolbarViewProps>

A custom view component for the toolbar that can contain any React elements. Useful for embedding custom components. It should only be used as a child of Toolbar.

The items within the view will be absolutely positioned, so flexbox styles will not work as expected.

Example

<Toolbar>
  <Toolbar.Spacer />
  <Toolbar.View>
    <TextInput
      placeholder="Search"
      placeholderTextColor={Color.ios.placeholderText}
    />
  </Toolbar.View>
  <Toolbar.View separateBackground>
    <Pressable style={{ width: 32, height: 32 }} onPress={handlePress}>
      <SymbolView name="plus" size={22} />
    </Pressable>
  </Toolbar.View>
</Toolbar>

ToolbarViewProps

`children`

iOS

Optional • Type: ReactNode