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#

1toolbar?: ToolBarProps

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.