Toolbar and Menus

Declarative Stack.Toolbar items plus the ToolbarHost, BarButtonItem, and MenuAction primitives on iOS

Declarative native toolbar items through Stack.Toolbar, in the same compound style as Stack.Header. One toolbar declares one placement: left and right compile to native header items while bottom, the default, renders a native UIToolbar at the bottom of the screen. This is the UIKit toolbar, distinct from the SwiftUI toolbar in iOS Navigation and Toolbar.

For explicit item identifiers or native item props the declarative API does not forward, drop to the lower-level primitives: One.iOS.ToolbarHost with One.iOS.BarButtonItem children, each a UIBarButtonItem, and One.iOS.MenuAction for UIMenu and UIAction elements.

Usage

import { Stack } from 'one'

function IndexToolbar({ edit, share }: { edit: () => void; share: () => void }) {
  return (
    <Stack.Screen name="index">
      <Stack.Toolbar placement="left">
        <Stack.Toolbar.Button icon="pencil" onPress={edit}>
          Edit
        </Stack.Toolbar.Button>
      </Stack.Toolbar>
      <Stack.Toolbar placement="right">
        <Stack.Toolbar.Menu title="More" icon="ellipsis.circle">
          <Stack.Toolbar.MenuAction icon="square.and.arrow.up" onPress={share}>
            Share
          </Stack.Toolbar.MenuAction>
        </Stack.Toolbar.Menu>
      </Stack.Toolbar>
    </Stack.Screen>
  )
}

Each toolbar maps to header items on its side. Buttons take their label as text children, an icon SF Symbol name, and onPress; menus nest MenuAction children and Menu submenus.

How it works

Stack.Toolbar children are descriptors, never rendered views: the converters read them into native items. left maps to unstable_headerLeftItems and right to unstable_headerRightItems, the iOS header-item path in react-navigation, and forces the header visible. bottom renders through a toolbar host inside the screen’s view controller, with each button or menu becoming a UIBarButtonItem and menu actions becoming UIMenu and UIAction elements.

Options are route-local and dynamic. A toolbar rendered in route content applies through the screen’s navigation options, so screen state can drive items with no new API; asChild renders children as a custom header element instead of header items. An explicit toolbar always wins over incoming options on its own side: hidden items convert to nothing, so a toolbar whose items are all hidden writes an empty array and clears inherited items, while an absent toolbar preserves them.

Header items

left and right toolbars live in layout config or route content and set header items through navigation options. Children are Button, Menu, and Spacer descriptors; anything else warns in dev and is skipped. Spacer needs a fixed width here; the flexible form is bottom only.

import { Stack } from 'one'

function EditToolbar({ edit }: { edit: () => void }) {
  return (
    <Stack.Toolbar placement="left">
      <Stack.Toolbar.Button icon="pencil" onPress={edit}>
        Edit
      </Stack.Toolbar.Button>
      <Stack.Toolbar.Spacer width={12} />
    </Stack.Toolbar>
  )
}

Buttons take text children or a Label child, icon as an SF Symbol name or image source, tintColor including dynamic iOS values, variant, disabled, hidden, selected, and onPress. separateBackground opts out of the shared background and hidesSharedBackground hides it behind the item for iOS 26 Liquid Glass. Badge is left and right only; bottom throws in dev.

Bottom toolbar

bottom renders the navigation-controller toolbar in place and must mount in screen content, where the responder chain reaches the screen view controller. In layout config it warns and is ignored. Bottom items take the same props; the bottom bar takes SF Symbol strings for icons. Hide the bar by unmounting the toolbar or by setting hidden on its items.

import { Stack } from 'one'

function ComposerToolbar({ add, hidden }: { add: () => void; hidden: boolean }) {
  return (
    <Stack.Toolbar>
      <Stack.Toolbar.Button icon="plus" hidden={hidden} onPress={add}>
        Add
      </Stack.Toolbar.Button>
      <Stack.Toolbar.Spacer />
      <Stack.Toolbar.SearchBarSlot />
    </Stack.Toolbar>
  )
}

Spacer without a width is flexible here, and SearchBarSlot embeds the screen search bar. The bottom toolbar renders nothing off iOS.

ToolbarHost

One.iOS.ToolbarHost is the lower-level bottom-UIToolbar renderer that a bottom Stack.Toolbar builds on. Reach for it directly only when you need explicit item identifiers or native item props the declarative API does not forward.

import { One } from 'one'

function BottomBar({ edit }: { edit: () => void }) {
  return (
    <One.iOS.ToolbarHost>
      <One.iOS.BarButtonItem identifier="edit" title="Edit" systemImageName="pencil" onSelected={edit} />
    </One.iOS.ToolbarHost>
  )
}

MenuAction

One.iOS.MenuAction is a native iOS UIMenu and UIAction element for context menus in toolbars. icon takes an SF Symbol name.

import { One } from 'one'

function RowActions() {
  return (
    <>
      <One.iOS.MenuAction
        identifier="edit"
        title="Edit"
        icon="pencil"
        onSelected={() => console.log('edit')}
      />
      <One.iOS.MenuAction
        identifier="delete"
        title="Delete"
        icon="trash"
        destructive
        onSelected={() => console.log('delete')}
      />
    </>
  )
}

Platform differences

Limits and gotchas

• Bottom toolbars mount in screen content. A bottom toolbar in layout config warns and is ignored; the host must sit inside the screen view controller.
• An explicit toolbar clears its side. Declared items replace inherited ones, so all hidden means an empty bar. An absent toolbar preserves them.
• Spacers differ by side. Left and right spacers need a fixed width; only the bottom bar takes flexible spacers and the search bar slot.
• Badges are header only. A badge in a bottom toolbar throws in dev.

Credit

The native toolbar, menu action, and font helpers are adapted from Expo Router.