Proposal: Adding a Expander Control to the set of WinUI controls.

Proposal: WinUI Expander Control

A spec has been opened with a PR for this issue. Feel free to continue general discussion in this proposal!

Summary

Throughout Windows, different expander controls are used by Windows Security, Settings, Photos, Paint 3D, the Notification Center, 3D Viewer, Toasts and the UWP Onedrive app. There’s currently no consistent “Windows” way of addressing this common UX pattern. An Expander control is motivated by both its use in many app scenarios and achieving parity with WPF.

Rationale

• There should be a built-in and consistent Fluent way to expand and collapse content.
• Expander scenarios exist across many surfaces that are not aligned in behavior and style, including being Narrator-friendly, keyboard controls, animations, designs, and high contrast changes.

Scope

Capability	Priority
Provide consistent expander behavior across WinUI apps	Must
Expand in size (pushing other content) and collapse based on user interaction with the control	Must
Support controls like Button, ToggleSwitch in the unexpanded and expanded content	Must
Support Expanding in all 4 directions	Should*
Support modifying all content (including the header) in expanded state	Could
Support expanding an InfoBar (open question on implementation)	Could
Include “accordion behavior” logic between Expanders	Won’t
Be light dismissible	Won’t

*The v1 Expander could be scoped to only expand in the downwards direction, with default down and ExpandDirection added later.

Important Notes

Proposed API

Public enum ExpandDirection 
{ 
Down = 0 
Up = 1 
Left = 2 
Right = 3 
} 

public class Expander : ContentControl 
{ 
Expander(); 

public object Header {get;set;} 
public DataTemplate HeaderTemplate { get;set; } 
public DataTemplate HeaderTemplateSelector {get;set;} 

public static readonly DependencyProperty HeaderProperty; 
public static readonly DependencyProperty HeaderTemplateProperty; 
public static readonly DependencyProperty HeaderTemplateSelectorProperty {get;} 

public bool IsExpanded { get;set} 
public ExpandDirection ExpandDirection { get;set;} 

protected virtual void OnExpanded(); 
protected virtual void OnCollapsed();

public event Expanded; 
public event Collapsed; 

public static readonly DependencyProperty IsExpandedProperty; 
public static readonly DependencyProperty ExpandDirectionProperty; 
} 

Visual States:  
ExpandStates: Expanded/Collapsed 

Accessibility: 
Support Expand/Collapse pattern (IExpandCollapseProvider) 

Expander Controls Elsewhere

• WPF
• Windows Community Toolkit
• Telerik UI
• Xamarin.Forms
• Syncfusion.XForms.Expander
• Avalonia UI

Examples of Expander Scenarios

Open Questions

• In discussion with the WinUI team, it was brought up that a V1 scoped to expand downward would shorten development time and make Expander available for developers sooner (as the scenarios for Expander thus far have all been downward), and a planned V2 could add ExpandDirection soon after. In your apps, are there any scenarios where Expander would need to expand in directions other than downward?

• How should Expander work with InfoBar? Adding expanding functionality to InfoBar? Putting InfoBar as the content of an Expander? The reverse?

[mdtauk]

Welcome to the WinUI project @kat-y - Xaml has a long history but can be a little quirky to those new to it. While WinUI is an opportunity to rethink how things work, in this case, expander is a relatively simple control and so a simple move from WPF to WinUI should suffice.

@robloo I disagree with your assertion that there is no need to re-engineer the XAML control template. WPF AFAIR has a number of chrome like elements which would be out of place in WinUI/Fluent.

Handling the Chevron and touch target sizes, as well as using the font scaling sizes. The Chevron should be easy to remove, or to add.

This example has a chevron in line with the text.

This example has no chevron at all

This example has a preceding side facing chevron

---

As for the implementation, there should be an animated transition when opening and closing, unless the user has turned off animations, then it just switches states.

[kat-y]

I’ve added initial info to the Expander spec and opened a PR - please feel free to continue spec discussion there! It’s PR 100 on the spec repo 😄