1# Toolbars and headers
2 
3Add native iOS toolbar items to Stack screens. Items can be placed in the header (left/right) or in a bottom toolbar area.
4 
5**Important:** iOS only. Available in Expo SDK 55+.
6 
7## Notes app example
8 
9```tsx
10import { Stack } from "expo-router";
11import { ScrollView } from "react-native";
12 
13export default function FoldersScreen() {
14  return (
15    <>
16      {/* ScrollView must be the first child of the screen */}
17      <ScrollView
18        style={{ flex: 1 }}
19        contentInsetAdjustmentBehavior="automatic"
20      >
21        {/* Screen content */}
22      </ScrollView>
23      <Stack.Screen.Title large>Folders</Stack.Screen.Title>
24      <Stack.SearchBar placeholder="Search" onChangeText={() => {}} />
25      {/* Header toolbar - right side */}
26      <Stack.Toolbar placement="right">
27        <Stack.Toolbar.Button icon="folder.badge.plus" onPress={() => {}} />
28        <Stack.Toolbar.Button onPress={() => {}}>Edit</Stack.Toolbar.Button>
29      </Stack.Toolbar>
30 
31      {/* Bottom toolbar */}
32      <Stack.Toolbar placement="bottom">
33        <Stack.Toolbar.SearchBarSlot />
34        <Stack.Toolbar.Button
35          icon="square.and.pencil"
36          onPress={() => {}}
37          separateBackground
38        />
39      </Stack.Toolbar>
40    </>
41  );
42}
43```
44 
45## Mail inbox example
46 
47```tsx
48import { Color, Stack } from "expo-router";
49import { useState } from "react";
50import { ScrollView, Text, View } from "react-native";
51 
52export default function InboxScreen() {
53  const [isFilterOpen, setIsFilterOpen] = useState(false);
54  return (
55    <>
56      <ScrollView
57        style={{ flex: 1 }}
58        contentInsetAdjustmentBehavior="automatic"
59        contentContainerStyle={{ paddingHorizontal: 16 }}
60      >
61        {/* Screen content */}
62      </ScrollView>
63      <Stack.Screen options={{ headerTransparent: true }} />
64      <Stack.Screen.Title>Inbox</Stack.Screen.Title>
65      <Stack.SearchBar placeholder="Search" onChangeText={() => {}} />
66      {/* Header toolbar - right side */}
67      <Stack.Toolbar placement="right">
68        <Stack.Toolbar.Button onPress={() => {}}>Select</Stack.Toolbar.Button>
69        <Stack.Toolbar.Menu icon="ellipsis">
70          <Stack.Toolbar.Menu inline>
71            <Stack.Toolbar.Menu inline title="Sort By">
72              <Stack.Toolbar.MenuAction isOn>
73                Categories
74              </Stack.Toolbar.MenuAction>
75              <Stack.Toolbar.MenuAction>List</Stack.Toolbar.MenuAction>
76            </Stack.Toolbar.Menu>
77            <Stack.Toolbar.MenuAction icon="info.circle">
78              About categories
79            </Stack.Toolbar.MenuAction>
80          </Stack.Toolbar.Menu>
81          <Stack.Toolbar.MenuAction icon="person.circle">
82            Show Contact Photos
83          </Stack.Toolbar.MenuAction>
84        </Stack.Toolbar.Menu>
85      </Stack.Toolbar>
86 
87      {/* Bottom toolbar */}
88      <Stack.Toolbar placement="bottom">
89        <Stack.Toolbar.Button
90          icon="line.3.horizontal.decrease"
91          selected={isFilterOpen}
92          onPress={() => setIsFilterOpen((prev) => !prev)}
93        />
94        <Stack.Toolbar.View hidden={!isFilterOpen}>
95          <View style={{ width: 70, height: 32, justifyContent: "center" }}>
96            <Text style={{ fontSize: 12, fontWeight: 700 }}>Filter by</Text>
97            <Text
98              style={{
99                fontSize: 12,
100                fontWeight: 700,
101                color: Color.ios.systemBlue,
102              }}
103            >
104              Unread
105            </Text>
106          </View>
107        </Stack.Toolbar.View>
108        <Stack.Toolbar.Spacer />
109        <Stack.Toolbar.SearchBarSlot />
110        <Stack.Toolbar.Button
111          icon="square.and.pencil"
112          onPress={() => {}}
113          separateBackground
114        />
115      </Stack.Toolbar>
116    </>
117  );
118}
119```
120 
121## Placement
122 
123- `"left"` - Header left
124- `"right"` - Header right
125- `"bottom"` (default) - Bottom toolbar
126 
127## Components
128 
129### Button
130 
131- Icon button: `<Stack.Toolbar.Button icon="star.fill" onPress={() => {}} />`
132- Text button: `<Stack.Toolbar.Button onPress={() => {}}>Done</Stack.Toolbar.Button>`
133 
134**Props:** `icon`, `image`, `onPress`, `disabled`, `hidden`, `variant` (`"plain"` | `"done"` | `"prominent"`), `tintColor`
135 
136### Menu
137 
138Dropdown menu for grouping actions.
139 
140```tsx
141<Stack.Toolbar.Menu icon="ellipsis">
142  <Stack.Toolbar.Menu inline>
143    <Stack.Toolbar.MenuAction>Sort by Recently Added</Stack.Toolbar.MenuAction>
144    <Stack.Toolbar.MenuAction isOn>
145      Sort by Date Captured
146    </Stack.Toolbar.MenuAction>
147  </Stack.Toolbar.Menu>
148  <Stack.Toolbar.Menu title="Filter">
149    <Stack.Toolbar.Menu inline>
150      <Stack.Toolbar.MenuAction isOn icon="square.grid.2x2">
151        All Items
152      </Stack.Toolbar.MenuAction>
153    </Stack.Toolbar.Menu>
154    <Stack.Toolbar.MenuAction icon="heart">Favorites</Stack.Toolbar.MenuAction>
155    <Stack.Toolbar.MenuAction icon="photo">Photos</Stack.Toolbar.MenuAction>
156    <Stack.Toolbar.MenuAction icon="video">Videos</Stack.Toolbar.MenuAction>
157  </Stack.Toolbar.Menu>
158</Stack.Toolbar.Menu>
159```
160 
161**Menu Props:** All Button props plus `title`, `inline`, `palette`, `elementSize` (`"small"` | `"medium"` | `"large"`)
162 
163**MenuAction Props:** `icon`, `onPress`, `isOn`, `destructive`, `disabled`, `subtitle`
164 
165When creating a palette with dividers, use `inline` combined with `elementSize="small"`. `palette` will not apply dividers on iOS 26.
166 
167### Spacer
168 
169```tsx
170<Stack.Toolbar.Spacer />           // Bottom toolbar - flexible
171<Stack.Toolbar.Spacer width={16} /> // Header - requires explicit width
172```
173 
174### View
175 
176Embed custom React Native components. When adding a custom view make sure that there is only a single child with **explicit width and height**.
177 
178```tsx
179<Stack.Toolbar.View>
180  <View style={{ width: 70, height: 32, justifyContent: "center" }}>
181    <Text style={{ fontSize: 12, fontWeight: 700 }}>Filter by</Text>
182  </View>
183</Stack.Toolbar.View>
184```
185 
186You can pass custom components to views as well:
187 
188```tsx
189function CustomFilterView() {
190  return (
191    <View style={{ width: 70, height: 32, justifyContent: "center" }}>
192      <Text style={{ fontSize: 12, fontWeight: 700 }}>Filter by</Text>
193    </View>
194  );
195}
196...
197<Stack.Toolbar.View>
198  <CustomFilterView />
199</Stack.Toolbar.View>
200```
201 
202## Recommendations
203 
204- When creating more complex headers, extract them to a single component
205 
206```tsx
207export default function Page() {
208  return (
209    <>
210      <ScrollView>{/* Screen content */}</ScrollView>
211      <InboxHeader />
212    </>
213  );
214}
215 
216function InboxHeader() {
217  return (
218    <>
219      <Stack.Screen.Title>Inbox</Stack.Screen.Title>
220      <Stack.SearchBar placeholder="Search" onChangeText={() => {}} />
221      <Stack.Toolbar placement="right">{/* Toolbar buttons */}</Stack.Toolbar>
222    </>
223  );
224}
225```
226 
227- When using `Stack.Toolbar`, make sure that all `Stack.Toolbar.*` components are wrapped inside `Stack.Toolbar` component.
228 
229This will **not work**:
230 
231```tsx
232function Buttons() {
233  return (
234    <>
235      <Stack.Toolbar.Button icon="star.fill" onPress={() => {}} />
236      <Stack.Toolbar.Button onPress={() => {}}>Done</Stack.Toolbar.Button>
237    </>
238  );
239}
240 
241function Page() {
242  return (
243    <>
244      <ScrollView>{/* Screen content */}</ScrollView>
245      <Stack.Toolbar placement="right">
246        <Buttons /> {/* ❌ This will NOT work */}
247      </Stack.Toolbar>
248    </>
249  );
250}
251```
252 
253This will work:
254 
255```tsx
256function ToolbarWithButtons() {
257  return (
258    <Stack.Toolbar>
259      <Stack.Toolbar.Button icon="star.fill" onPress={() => {}} />
260      <Stack.Toolbar.Button onPress={() => {}}>Done</Stack.Toolbar.Button>
261    </Stack.Toolbar>
262  );
263}
264 
265function Page() {
266  return (
267    <>
268      <ScrollView>{/* Screen content */}</ScrollView>
269      <ToolbarWithButtons /> {/* ✅ This will work */}
270    </>
271  );
272}
273```
274 
275## Limitations
276 
277- iOS only
278- `placement="bottom"` can only be used inside screen components (not in layout files)
279- `Stack.Toolbar.Badge` only works with `placement="left"` or `"right"`
280- Header Spacers require explicit `width`
281 
282## Reference
283 
284Docs https://docs.expo.dev/versions/unversioned/sdk/router - read to see the full API.
285