Display toolbar items

The .NET Multi-platform App UI (.NET MAUI) ToolbarItem class is a special type of button that can be added to a Page object's ToolbarItems collection. Because the Shell class derives from Page, ToolbarItem objects can also be added to the ToolbarItems collection of a Shell object. Each ToolbarItem object will appear as a button in the app's navigation bar. A ToolbarItem object can have an icon and appear as a primary or secondary item. The ToolbarItem class inherits from MenuItem.

The following screenshot shows a ToolbarItem object in the navigation bar on iOS:

The ToolbarItem class defines the following properties:

• Order, of type ToolbarItemOrder, determines whether the ToolbarItem object displays in the primary or secondary menu.
• Priority, of type int, determines the display order of items in a ToolbarItems collection.

The ToolbarItem class inherits the following typically used properties from the MenuItem class:

• Command, of type ICommand, allows binding user actions, such as finger taps or clicks, to commands defined on a viewmodel.
• CommandParameter, of type object, specifies the parameter that should be passed to the Command.
• IconImageSource, of type ImageSource, that determines the display icon on a ToolbarItem object.
• Text, of type string, determines the display text on a ToolbarItem object.

These properties are backed by BindableProperty objects, which means that they can be targets of data bindings.

Note

An alternative to creating a toolbar from ToolbarItem objects is to set the TitleViewProperty attached property to a layout class that contains multiple views. For more information, see Display views in the navigation bar.

Create a ToolbarItem

To create a toolbar item, create a ToolbarItem object and set its properties to define its appearance and behavior. The following example shows how to create a ToolbarItem with minimal properties set, and add it to a ContentPage's ToolbarItems collection:

<ContentPage.ToolbarItems>
    <ToolbarItem Text="Add item"
                 IconImageSource="add.png" />
</ContentPage.ToolbarItems>

This example results in a ToolbarItem object that has text and an icon. However, the appearance of a ToolbarItem varies across platforms.

A ToolbarItem can also be created in code and added to the ToolbarItems collection:

ToolbarItem item = new ToolbarItem
{
    Text = "Add item",
    IconImageSource = ImageSource.FromFile("add.png")
};

// "this" refers to a Page object
this.ToolbarItems.Add(item);

Note

Images can be stored in a single location in your app project. For more information, see Add images to a .NET MAUI project.

Define button behavior

The ToolbarItem class inherits the Clicked event from the MenuItem class. An event handler can be attached to the Clicked event to react to taps or clicks on ToolbarItem objects:

<ToolbarItem ...
             Clicked="OnItemClicked" />

An event handler can also be attached in code:

ToolbarItem item = new ToolbarItem { ... };
item.Clicked += OnItemClicked;

These examples reference an OnItemClicked event handler, which is shown in the following example:

void OnItemClicked(object sender, EventArgs e)
{
    ToolbarItem item = (ToolbarItem)sender;
    messageLabel.Text = $"You clicked the \"{item.Text}\" toolbar item.";
}

Note

ToolbarItem objects can also use the Command and CommandParameter properties to react to user input without event handlers.

Enable or disable a ToolbarItem at runtime

To enable or disable a ToolbarItem at runtime, bind its Command property to an ICommand implementation, and ensure that its canExecute delegate enables and disables the ICommand as appropriate.

Important

Don't bind the IsEnabled property to another property when using the Command property to enable or disable the ToolbarItem.

Primary and secondary toolbar items

The ToolbarItemOrder enum has Default, Primary, and Secondary values.

When the Order property is set to Primary, the ToolbarItem object appears in the navigation bar on all platforms. ToolbarItem objects are prioritized over the page title, which will be truncated to make room for the items.

When the Order property is set to Secondary, behavior varies across platforms. On iOS and Mac Catalyst, Secondary toolbar items are grouped into a pull‑down menu, shown under a system ellipsis icon in the navigation bar. Items within this menu are ordered by their Priority value. On Android and Windows, the Secondary items menu appears as three dots that can be tapped:

Tapping the three dots reveals items in a vertical list:

Warning

Icon behavior in ToolbarItem objects that have their Order property set to Secondary can be inconsistent across platforms. Avoid setting the IconImageSource property on items that appear in the secondary menu.

Example: order secondary items by priority (iOS and Mac Catalyst)

On iOS and Mac Catalyst, secondary items are shown in a pull‑down menu ordered by their Priority (lower values appear first):

<ContentPage.ToolbarItems>
    <ToolbarItem Text="Settings" Order="Secondary" Priority="0" />
    <ToolbarItem Text="Feedback" Order="Secondary" Priority="1" />
    <ToolbarItem Text="About" Order="Secondary" Priority="2" />
    <ToolbarItem Text="Help" Order="Secondary" Priority="3" />
    <ToolbarItem Text="Sign out" Order="Secondary" Priority="100" />
</ContentPage.ToolbarItems>

Tip

Keep labels short so they fit comfortably in the pull‑down. Avoid icons for Secondary items due to platform inconsistency.