As of .NET 10, iOS and macOS support secondary toolbar items, which are found in overflow menus and make a .NET MAUI app feel more native to the Apple user experience.
When we talk about technology, we think of a world of constant changes that each day focuses on improving the previous one. In the case of .NET MAUI, this is no exception; in .NET 10, many very interesting improvements were released to make our work as devs increasingly more efficient.
This is the case with secondary toolbar Items, an improvement focused directly on the user experience. Previously, their behavior was not consistent across all platforms, especially on iOS and macOS. Now, we have support that allows secondary actions to behave in a more natural way and align with the Apple conventions, making our applications feel much more native.
These are options that live in the toolbar. Instead of being displayed directly in the toolbar, they are grouped inside a secondary menu that is shown when selecting their primary action.
For example: Location → North America.
This way, only the most important actions remain visible in the main toolbar, which helps reduce visual clutter and improves the user experience.
From .NET 10 onward, the official documentation states:
“iOS and macOS now support secondary toolbar items, providing better alignment with platform conventions.” 😍
This improvement is not just a visual change; it introduces several important enhancements for iOS and macOS that directly impact how secondary toolbar items behave and integrate with the platform, making them feel much more native, such as:
<ToolbarItem Text="Copy" Order="Secondary" />
<ToolbarItem Text="Paste" Order="Secondary"/>
When configuring ToolbarItems, we need to define whether they will be primary or secondary. With this improvement, all items marked in the Order property with the value Secondary are automatically grouped into the secondary menu, which means we don’t need to add any extra configuration or write additional code for it to work.
This is especially valuable when we want to maintain a native experience in our applications.
<ToolbarItem Text="Share" Order="Secondary" />
.NET MAUI now uses iOS 13+ APIs, which means it displays a modern menu design to present secondary options. This design follows the established rules and respects the Human Interface Guidelines.
The Human Interface Guidelines (HIG) are a set of design recommendations created by Apple, which align a unique and consistent experience across its platforms, indicating how applications should look and behave.
You can define the order of your items! 😎
<ToolbarItem Text="Go to document" Order="Secondary" Priority="0" />
Keeping a logical order in your items is also important. When adding a ToolbarItem, there is a property called Priority, which is responsible for defining the order in which the options will be displayed in the menu, both primary and secondary.
Items are ordered numerically, from lowest to highest, starting at 0. This allows us to decide which actions should appear first, helping maintain a clear hierarchy of what we want to present to the user.
The secondary menu is displayed by default on the right side of the toolbar. It also has the ability to automatically adapt when Right-To-Left (RTL) is enabled in your app.
In case you didn’t know, RTL refers to the reading and writing direction of certain languages. This means your .NET MAUI app respects the conventions of each language, providing a more accessible and adaptable user experience. This behavior applies to all visual elements, including the secondary menu.
By default, secondary toolbar items are grouped into a pull-down menu that uses the system ellipsis (⋯) icon (UIImage.GetSystemImage("ellipsis.circle")). This icon, defined by Apple in its Human Interface Guidelines, is used to represent additional, secondary or less frequent actions, so that the menu looks and behaves like any other native menu on iOS and macOS.
Although this icon is recommended, it is not mandatory. If your app requires a different visual representation, .NET MAUI allows you to customize the icon, enabling the secondary menu to better align with your app’s visual requirements while preserving its native behavior.
⚠️ My recommendation is that whenever this icon needs to be changed, it’s important for the design team to be aligned and aware that a rule defined by Apple is being modified. There’s nothing wrong with changing it, but it’s essential to have a clear WHY behind the decision.
Another important detail to highlight is that this menu is dynamic. If the menu is open and any of an item’s properties change at runtime—such as its text, enabled state or visibility—the system automatically rebuilds and closes the menu to reflect those updates.
This allows users to always see up-to-date and consistent information, preventing invalid actions and maintaining a reliable, native user experience.
💡 The official documentation recommends keeping label text short so it fits in the dropdown menu, thus reducing the risk of cross-platform inconsistencies.
A basic XAML implementation about a ToolbarItems implementation, would look like the following example:
<ContentPage.ToolbarItems>
<!-- Primary toolbar items -->
<ToolbarItem Text="Save" Order="Primary" Priority="0" />
<ToolbarItem Text="Edit" Order="Primary" Priority="1" />
<!-- Secondary toolbar items -->
<ToolbarItem Text="Share" Order="Secondary" Priority="0" />
<ToolbarItem Text="Delete" Order="Secondary" Priority="1" />
<ToolbarItem Text="Settings" Order="Secondary" Priority="2" />
</ContentPage.ToolbarItems>
Example obtained from official documentation.
And that’s it! 🎉 With .NET 10, secondary toolbar items in .NET MAUI take an important step forward, especially on iOS and macOS. These improvements bring a more native, consistent and predictable behavior by aligning toolbar actions with platform conventions, that is why it’s important to keep you up to date with the news!
If you have any questions or would like me to dive deeper into related topics, feel free to leave a comment—I’ll be happy to help! 💚
See you in the next article! 🙋♀️✨
The explanation was based on the official documentation:
Leomaris Reyes is a Software Engineer from the Dominican Republic, with more than 5 years of experience. A Xamarin Certified Mobile Developer, she is also the founder of Stemelle, an entity that works with software developers, training and mentoring with a main goal of including women in Tech. Leomaris really loves learning new things! 💚💕 You can follow her: Twitter, LinkedIn , AskXammy and Medium.