Toolbars
The toolbar
property allows you to populate the navigation bar, bottom toolbar, or keyboard accessory area with custom UI elements. This system is modeled after SwiftUI’s toolbar API and provides fine-grained placement control across various regions of the user interface.
This feature is useful for adding primary or contextual actions, organizing control groups, and enhancing keyboard interactions.
Definition
ToolBarProps
1type ToolBarProps = {
2 bottomBar?: VirtualNode | VirtualNode[]
3 cancellationAction?: VirtualNode | VirtualNode[]
4 confirmationAction?: VirtualNode | VirtualNode[]
5 destructiveAction?: VirtualNode | VirtualNode[]
6 keyboard?: VirtualNode | VirtualNode[]
7 navigation?: VirtualNode | VirtualNode[]
8 primaryAction?: VirtualNode | VirtualNode[]
9 principal?: VirtualNode | VirtualNode[]
10 topBarLeading?: VirtualNode | VirtualNode[]
11 topBarTrailing?: VirtualNode | VirtualNode[]
12}
Placement Options
Each property of ToolBarProps
determines where the specified items will be placed. You can use either a single VirtualNode
or an array of nodes for each region.
automatic
(implicit): Lets the system decide optimal placement based on context. Not explicitly defined as a prop.
bottomBar
: Adds items to the bottom toolbar.
cancellationAction
: Represents a cancellation action, typically used in modal contexts.
confirmationAction
: Represents a confirmation action, typically used in modal contexts.
destructiveAction
: Represents a destructive action, often styled with visual emphasis (e.g., red).
keyboard
: Displays the item in the keyboard accessory view when a text input is focused.
navigation
: Represents a navigation action (e.g., back or close).
primaryAction
: Marks an item as the primary action in the current context.
principal
: Positions the item in the center of the top navigation bar.
topBarLeading
: Places items on the leading edge (left in LTR languages) of the top navigation bar.
topBarTrailing
: Places items on the trailing edge (right in LTR languages) of the top navigation bar.
Example
1<VStack
2 navigationTitle={"Toolbars"}
3 navigationBarTitleDisplayMode={"inline"}
4 toolbar={{
5 topBarTrailing: [
6 <Button
7 title={"Select"}
8 action={() => {}}
9 />,
10 <ControlGroup
11 label={
12 <Button
13 title={"Add"}
14 systemImage={"plus"}
15 action={() => {}}
16 />
17 }
18 controlGroupStyle={"palette"}
19 >
20 <Button
21 title={"New"}
22 systemImage={"plus"}
23 action={() => {}}
24 />
25 <Button
26 title={"Import"}
27 systemImage={"square.and.arrow.down"}
28 action={() => {}}
29 />
30 </ControlGroup>
31 ],
32 bottomBar: [
33 <Button
34 title={"New Sub Category"}
35 action={() => {}}
36 />,
37 <Button
38 title={"Add category"}
39 action={() => {}}
40 />
41 ],
42 keyboard: <HStack padding>
43 <Spacer />
44 <Button
45 title={"Done"}
46 action={() => {
47 Keyboard.hide()
48 }}
49 />
50 </HStack>
51 }}
52>
53 <TextField
54 title={"TextField"}
55 value={text}
56 onChanged={setText}
57 textFieldStyle={"roundedBorder"}
58 prompt={"Focus to show the keyboard toolbar"}
59 />
60</VStack>
This example demonstrates:
- A top bar with a "Select" button and a control group offering "New" and "Import" options.
- A bottom toolbar with actions for creating categories.
- A keyboard accessory view with a “Done” button aligned to the right, which hides the keyboard when pressed.
Notes
- All toolbar items support dynamic updates—changes in state will automatically reflect in the toolbar UI.
- Items placed in the
keyboard
section will only be visible when a text input field is focused.
ControlGroup
components are useful for grouping related toolbar buttons visually and functionally.