Secondary ToolbarItems in .NET MAUI 10 on iOS and macOS

Sometimes the small things make a big difference. In .NET MAUI, ToolbarItem has an Order property that lets you mark an item as Primary or Secondary. Primary actions stay directly visible in the toolbar. Secondary actions are the ones that belong in the overflow menu.

With .NET MAUI 10, the iOS and macOS rendering for secondary ToolbarItems has been improved. Instead of trying to force these actions into a place where they do not really belong, they are exposed through the native overflow menu from the navigation bar. That feels much more at home on iOS and macOS.

The Shell part of this change was added in dotnet/maui#30480, building on earlier iOS/macOS ToolbarItem work. The result is that pages can keep the most important action visible, while less frequently used actions are tucked away in the platform menu.

Secondary ToolbarItems on Shell pages now use a native overflow-style menu on iOS and macOS.

Using Secondary ToolbarItems #

The XAML looks exactly like you would expect. Add your toolbar items to the ContentPage.ToolbarItems collection and set Order="Secondary" for the items that should go into the overflow menu.

While this example uses Shell, the syntax is exactly the same for non-Shell pages: define your items in ContentPage.ToolbarItems and set Order="Secondary".

<ContentPage
    x:Class="MauiSecondaryToolbarSample.MainPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    Title="Secondary Toolbar Sample">

    <ContentPage.ToolbarItems>
        <ToolbarItem
            Text="Primary"
            Order="Primary"
            Clicked="OnToolbarItemClicked" />

        <ToolbarItem
            Text="Secondary A"
            Order="Secondary"
            Clicked="OnToolbarItemClicked" />

        <ToolbarItem
            Text="Secondary B"
            Order="Secondary"
            Clicked="OnToolbarItemClicked" />

        <ToolbarItem
            Text="Secondary C"
            Order="Secondary"
            Clicked="OnToolbarItemClicked" />
    </ContentPage.ToolbarItems>

    <VerticalStackLayout Padding="24" Spacing="16">
        <Label Text="Tap the overflow menu to see the secondary items." />
    </VerticalStackLayout>
</ContentPage>

On iOS, the primary item stays visible in the navigation bar. The secondary items are exposed from the overflow button in that same navigation bar.

A .NET MAUI 10 Shell app running on the iOS simulator with a primary toolbar item and the overflow button in the navigation bar.

And when you tap the overflow button, the secondary items are shown in the native iOS menu.

The native iOS menu showing Secondary A, Secondary B, and Secondary C from the Shell page toolbar.

Where This Applies #

The sample is specifically about Shell pages on iOS and macOS because that is where dotnet/maui#30480 comes in. It does not require a new API and you do not have to write platform-specific code. You keep using ContentPage.ToolbarItems; .NET MAUI handles the native rendering for you.

For the sample I used Microsoft.Maui.Controls version 10.0.70. If you want to try it yourself, I published the full sample here:

github.com/jfversluis/MauiSecondaryToolbarSample

Clone it, run it on iOS or macOS, and check the toolbar menu. No custom handlers, no platform-specific code, just the regular ToolbarItem API.

Wrapping Up #

This is one of those improvements that makes cross-platform UI code feel a little more native without changing your app code. If you have Shell pages with secondary toolbar actions, .NET MAUI 10 is a good moment to test them on iOS and macOS again.