Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
The Expander control provides an expandable container to host any content. The control has two main properties to store your content:
Header
This Header property can be provided with any view to allow for full customization. The Header will always be visible and interacting with it (clicking, tapping, or using the keyboard or a screen reader) will show/collapse the Content. See Accessibility.
Note
It is not recommended to place controls inside the header that allow user interaction. VoiceOver doesn't read a header that holds a control as one button, so that it can still reach the control.
Content
This is the main content that will show when the Header property is interacted with it (clicked or tapped) or the IsExpanded property is modified.
Note
Expander may work unexpectedly if it is placed inside ListView or CollectionView. However, it can be controlled with the custom implementation by setting public Action<TappedEventArgs>? HandleHeaderTapped { get; set; }. This action is executed each time the header is tapped. Please pay attention, by changing this action you may receive different behavior in CollectionView and ListView on all platforms.
Note
The Expander lays out its Header and Content in a Grid of its own. An implicit Style for Grid, for example one in App.xaml, doesn't apply to that Grid unless the Style sets ApplyToDerivedTypes. Even then the Background and BackgroundColor of that Grid stay null, so the background of the Expander shows behind the Header and the Content.

Basic usage
The following examples show how to use the Expander view by setting the Header property to be a Label control and the Content to be a HorizontalStackLayout with an Image and a Label inside.
XAML
Including the XAML namespace
In order to use the toolkit in XAML the following xmlns needs to be added into your page or view:
xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
Therefore the following:
<ContentPage
x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml">
</ContentPage>
Would be modified to include the xmlns as follows:
<ContentPage
x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit">
</ContentPage>
Using the Expander
The following example shows how to add an Expander view in XAML.
<toolkit:Expander>
<toolkit:Expander.Header>
<Label Text="Baboon"
FontAttributes="Bold"
FontSize="Medium" />
</toolkit:Expander.Header>
<HorizontalStackLayout Padding="10">
<Image Source="http://upload.wikimedia.org/wikipedia/commons/thumb/f/fc/Papio_anubis_%28Serengeti%2C_2009%29.jpg/200px-Papio_anubis_%28Serengeti%2C_2009%29.jpg"
Aspect="AspectFill"
HeightRequest="120"
WidthRequest="120" />
<Label Text="Baboons are African and Arabian Old World monkeys belonging to the genus Papio, part of the subfamily Cercopithecinae."
FontAttributes="Italic" />
</HorizontalStackLayout>
</toolkit:Expander>
C#
The following example shows how to add an Expander view in C#.
using CommunityToolkit.Maui.Views;
var expander = new Expander
{
Header = new Label
{
Text = "Baboon",
FontAttributes = FontAttributes.Bold,
FontSize = Device.GetNamedSize(NamedSize.Medium, typeof(Label))
}
};
expander.Content = new HorizontalStackLayout
{
Padding = new Thickness(10),
Children =
{
new Image
{
Source = "http://upload.wikimedia.org/wikipedia/commons/thumb/f/fc/Papio_anubis_%28Serengeti%2C_2009%29.jpg/200px-Papio_anubis_%28Serengeti%2C_2009%29.jpg",
Aspect = Aspect.AspectFill,
HeightRequest = 120,
WidthRequest = 120
},
new Label
{
Text = "Baboons are African and Arabian Old World monkeys belonging to the genus Papio, part of the subfamily Cercopithecinae.",
FontAttributes = FontAttributes.Italic
}
}
};
C# Markup
using CommunityToolkit.Maui.Views;
Content = new Expander
{
Header = new Label()
.Text("Baboon")
.Font(bold: true, size: 18),
Content = new HorizontalStackLayout
{
new Image()
.Source("http://upload.wikimedia.org/wikipedia/commons/thumb/f/fc/Papio_anubis_%28Serengeti%2C_2009%29.jpg/200px-Papio_anubis_%28Serengeti%2C_2009%29.jpg")
.Size(120)
.Aspect(Aspect.AspectFill),
new Label()
.Text("Baboons are African and Arabian Old World monkeys belonging to the genus Papio, part of the subfamily Cercopithecinae.")
.Font(italic: true)
}.Padding(10)
}.CenterHorizontal();
Accessibility
Keyboard and screen reader users can expand and collapse an Expander through its Header whenever a tap on the Header can: while the Header is visible, enabled and not input transparent. While a tap can't toggle the Expander, it offers no action to the keyboard or to a screen reader.
| Platform | Behavior |
|---|---|
| Windows | The Expander is a Tab stop. Enter and Space toggle it when they are released, like a Button, and pressing another key before the release cancels the toggle. The focus visual frames only the row of the Header. UI Automation exposes the Expander as a button with the class name Expander, and with the ExpandCollapse and Invoke patterns. Its name comes from the Header: the semantic description, the text, or the texts of the views a layout Header holds. Its help text comes from the SemanticProperties.Hint of the Header. The button is disabled while a tap can't toggle the Expander. It raises the ExpandCollapseState property changed event whenever IsExpanded changes, also when code changes it. |
| Android | TalkBack announces the Header as collapsed or expanded, and lists the expand action in its actions menu while the Expander is collapsed, and the collapse action while it is expanded. A double tap with TalkBack still taps the Header, which toggles the Expander. |
| iOS and Mac Catalyst | VoiceOver reads the whole Header as one button that a double tap toggles. The element has the button trait, the header trait when the Header is a heading, and the not enabled trait while a tap can't toggle the Expander. Its label, hint and AutomationId come from the Header. VoiceOver announces it as collapsed or expanded from iOS and Mac Catalyst 18. A Header that holds a control, such as a Button, a Switch or an Entry, keeps the default accessibility elements of UIKit, and VoiceOver doesn't announce the state of the Expander for it. A Header with another TapGestureRecognizer lets VoiceOver tap it, so that every recognizer runs. |
Every activation from the keyboard or from assistive technology goes through the same code as a tap, so IsExpanded, Command and CommandParameter, ExpandedChanged and HandleHeaderTapped behave as for a tap. In a CollectionView on Windows, such an activation still resizes the item that holds the Expander.
Important
HandleHeaderTapped also runs when the Header is activated without a tap: from the keyboard or by UI Automation on Windows, by the expand or collapse action of TalkBack on Android, and by VoiceOver on iOS and Mac Catalyst. For these activations TappedEventArgs.Parameter is null, and TappedEventArgs.GetPosition returns the center of the Header on Windows and null on Android, iOS and Mac Catalyst. A custom HandleHeaderTapped that assumes a pointer position must handle null.
The UseMauiCommunityToolkit method registers a handler for the layout of the Expander, which provides this on Windows, iOS and Mac Catalyst. A handler that your app registers for Grid no longer applies to the Grid of the Expander. Changes to LayoutHandler.Mapper still apply. If your app sets LayoutHandler.PlatformViewFactory, that factory doesn't create the platform view of the layout of the Expander on Windows, iOS and Mac Catalyst, because only the toolkit's own platform view provides this support. Your factory still creates the platform views of your other layouts, including the ones in the Header and the Content, and on Android also the platform view of the layout of the Expander.
UI tests
The accessibility support changes what UI automation finds:
- Windows: a button with the class name
Expander, named after theHeader, wraps theHeaderand theContentin the UI Automation tree. A test that finds theHeaderby name can match this element first, and its bounds include the expandedContent. The element of theHeaderitself, with itsAutomationId, is still there as a child. - iOS and Mac Catalyst: the views inside a
Headerare no longer separate accessibility elements, unless theHeaderholds a control. The element of theHeaderhas theAutomationIdof theHeader, so a query for a view inside a layoutHeaderby its ownAutomationId, for example with XCUITest or Appium, no longer finds it.
Properties
| Property | Type | Description |
|---|---|---|
Command |
ICommand |
Executes when IsExpanded changes, for example when the Expander header is tapped. |
CommandParameter |
object |
The parameter that's passed to Command. |
Direction |
ExpandDirection |
Defines the expander direction. |
Content |
IView? |
Defines the content to be displayed when the Expander expands. |
Header |
IView? |
Defines the header content. |
IsExpanded |
bool |
Determines if the Expander is expanded. This property uses the TwoWay binding mode, and has a default value of false. |
The ExpandDirection enumeration defines the following members:
| Value | Description |
|---|---|
Down |
Indicates that the Expander content is under the header. |
Up |
Indicates that the Expander content is above the header. |
The Expander control also defines an ExpandedChanged event that's fired when IsExpanded changes: when the Expander header is tapped, or activated from the keyboard or by assistive technology, and when code changes IsExpanded.
ExpandedChangedEventArgs
Event argument which contains Expander IsExpanded state.
Properties
| Property | Type | Description |
|---|---|---|
| IsExpanded | bool |
Determines if the Expander is expanded. |
Examples
You can find an example of this feature in action in the .NET MAUI Community Toolkit Sample Application.
API
You can find the source code for Expander over on the .NET MAUI Community Toolkit GitHub repository.
.NET MAUI Community Toolkit