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

[eduardoaguacate]

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?

[robloo]

Expander is very useful and I've been using the Windows Community Toolkit version since it was added. I wouldn't re-invent the wheel too much though, just porting over the code from the toolkit would be perfect for version 1.0 in my opinion.

Another example: the ColorPicker with it's 'MoreButton' could use this.

[kat-y]

Thanks so much for submitting this proposal! I'm going to make some edits, including differentiating between what I think are true Expander scenarios and what are more like Flyout/MenuFlyout uses.

[kat-y]

I've updated this proposal to include more details on the scope, a proposed API, and the following open question.

• Do we need to support ExpandDirection in a v1 Expander? Are there common app scenarios where Expander would need to expand in directions other than downward?

Would love feedback on how these fit or don't fit with your use cases for Expander!

[mdtauk]

I've updated this proposal to include more details on the scope, a proposed API, and the following open question.

• Do we need to support ExpandDirection in a v1 Expander? Are there common app scenarios where Expander would need to expand in directions other than downward?

Would love feedback on how these fit or don't fit with your use cases for Expander!

It does seem like a basic function of the control

[kat-y]

It does seem like a basic function of the control

@mdtauk do you see ExpandDirection other than downward being a common app scenario? The examples of Expander behaviors that I see are far more often expanding downwards - I would definitely like Expander to have ExpandDirection but is it necessary in a v1?

[robloo]

Yes, we need expand direction. There are many cases for using it and it would be an unnecessary breaking change to the control template after a v1 release to add it. The Expander API hasn't changed much since WPF and the proposal here has all the necessary properties/events/methods already. I would just implement it all in one shot and we can be done with this control. Design-wise the UWP Community Toolkit made the necessary changes to better work with touch. I think we have all the pieces and there is no need to re-invent anything.

Edit: The community toolkit also has a ContentOverlay property. That might be something to skip in a V1.

[kat-y]

Yes, we need expand direction. There are many cases for using it and it would be an unnecessary breaking change to the control template after a v1 release to add it.

@robloo Could you elaborate on how this would be a breaking change? My understanding is we could avoid it being breaking with V1 having downward expansion, and V2 could add ExpandDirection and default to downward.

[mdtauk]

It does seem like a basic function of the control

@mdtauk do you see ExpandDirection other than downward being a common app scenario? The examples of Expander behaviors that I see are far more often expanding downwards - I would definitely like Expander to have ExpandDirection but is it necessary in a v1?

Chat apps which load new list content from the bottom up being one of them maybe.

Beyond the very basic essential:

• IsCollapsed
• IsExpanding
• IsExpanded
• IsCollapsing

As well as IsEnabled

The next core thing is where to expand to.

• ExpandUp
• ExpandDown
• ExpandLeft
• ExpandRight

[kat-y]

Chat apps which load new list content from the bottom up being one of them maybe.

@mdtauk I don't fully understand what you mean with this chat apps example - could you elaborate?
As for the properties - the proposed API is based off the WPF Expander so I think IsExpanded and ExpandDirection would cover them. What would IsEnabled be used for - is there an app scenario where you'd want to disable an Expander?

[robloo]

Another example I've used in the past are secondary, editable properties that should usually be hidden. These are shown at the bottom of an editor only when clicking an 'options' button and the expander opens upwards. It's really just up to the design you are going for. There are many useful cases for expanding different directions and it seems unnecessary to artificially restrict this especially when past convention is so strong. I don't think any of this would be too difficult in a V1 of the control especially since all the problems have already been solved in the community toolkit and WPF.

@robloo Could you elaborate on how this would be a breaking change? My understanding is we could avoid it being breaking with V1 having downward expansion, and V2 could add ExpandDirection and default to downward.

https://github.com/windows-toolkit/WindowsCommunityToolkit/blob/master/Microsoft.Toolkit.Uwp.UI.Controls/Expander/Expander.xaml

I suppose if you are very careful in designing the template and visual states it is possible to make it non-breaking. However, to do that you really need to design the functionality anyway so you might as well implement it. This is all fairly basic and there is no reason for a V2 plan from the get-go on this control.

I know its enticing to re-invent the wheel. But please keep it so people porting apps from WPF to WinUI can do it without anything but absolutely necessary code changes. WinUI needs to start correcting some of the mistakes with UWP.

[robloo]

What would IsEnabled be used for - is there an app scenario where you'd want to disable an Expander?

@mdtauk Is correct, this needs to support IsEnabled as well. Disabling controls is pretty strong convention anytime there is the possibility of input or state change. Please don't make us defend that.

[JustABearOz]

In the screenshots above, windows security has an expander for the antivirus section as well as the left navigation menu. This shows a very realistic use of the expander in more than one direction that a lot of apps would need to support. My vote is for supporting multiple directions in V1.

[kat-y]

@robloo

Another example I've used in the past are secondary, editable properties that should usually be hidden. These are shown at the bottom of an editor only when clicking an 'options' button and the expander opens upwards.

Could you elaborate with a screenshot or specific app where this happens so I can understand the scenario more? I can think of editors where a options button opens a popup with more buttons, but in the ones I'm familiar with the other content isn't pushed upwards - a popup/flyout behavior rather than an expansion.

I suppose if you are very careful in designing the template and visual states it is possible to make it non-breaking. However, to do that you really need to design the functionality anyway so you might as well implement it. This is all fairly basic and there is no reason for a V2 plan from the get-go on this control.
I know its enticing to re-invent the wheel. But please keep it so people porting apps from WPF to WinUI can do it without anything but absolutely necessary code changes.

I agree with you that porting apps from WPF to WinUI should be as smooth as possible! 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. (I'll edit the open question to have this additional context) This is why I'm hoping to understand if there are specific use cases developers have for non-downward Expander! 😄

Disabling controls is pretty strong convention anytime there is the possibility of input or state change. Please don't make us defend that.

Thanks for explaining this, it totally makes sense that disabling the state change is a desired feature for this kind of control!

[kat-y]

In the screenshots above, windows security has an expander for the antivirus section as well as the left navigation menu. This shows a very realistic use of the expander in more than one direction that a lot of apps would need to support. My vote is for supporting multiple directions in V1.

@JustABearOz I think the left navigation menu is a NavigationView, actually. 😃 I agree that the antivirus section is an Expander scenario, in this case expanding downwards. Would love to know any specific use cases you have for non-downward Expander!

[JustABearOz]

@kat-y Ok, that takes away a need for left/right, but 2 examples in windows that seem to expand up that could easily apply to apps:
1: The screenshot above with the quick actions menu. Pretty sure that expands up.
2: In windows, the popup calendar form the system tray has a section which expand up to show agenda/appointments.

Is it possible to support Up/Down for V1 instead of just Down?

[kat-y]

1: The screenshot above with the quick actions menu. Pretty sure that expands up.

@JustABearOz thanks so much for bringing up these examples! For 1: I think this is an interesting edge case - the expansion is 'downwards' from the 'header' (the expand button), but the control itself is positioned at the bottom of the surface so the header (and the expanded content) has to 'shift' upwards (otherwise it would run off the screen!). Seems like a good way to handle having an expanding item at the 'bottom' of an app, do you agree?

2: In windows, the popup calendar form the system tray has a section which expand up to show agenda/appointments.
Is it possible to support Up/Down for V1 instead of just Down?

I agree with you, this is a scenario where the header is at the bottom of the area and expands up! In this case the calendar's expander (and the popup as a whole) is tied to the taskbar - have you encountered scenarios in apps where expanders have a similar tied positioning that necessitates upward expansion?

[robloo]

@kat-y I mean no offense but I feel like we are having to re-explain things that were known 15 years ago. I don't understand why you are asking us to give examples of expand direction in real-world usage. I expect internally you have to take this to spec review and defend it to management. But the explanation can simply be (1) you need to empower users to achieve their design targets, it's not up to Microsoft to say what is/is-not possible to do with controls it's up to app developers/designers to discover what is best for their use-case (a critical concept for look-less controls) (2) Most importantly, this is not a new idea at all. You are copying over an existing API in this area and need to maintain app compatiblity. Again, if this was a new idea I would understand more why we have to defend it -- it's good to make sure features are useful before investing the time in them.

Aside from the header there are literally two properties in this control and if it was C# I could write it in a few hours using the WCT base. We will spend more man-hours just talking about it than implementing it as it exists today in WPF/WCT.

[kat-y]

Thanks for the priority order @mdtauk!

I've added a new open question:

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

[mdtauk]

I would imagine it would replace the content, but I think those designing the information bar should provide a design spec for a collapsible bar, which the expander designers can look at.

It's a conversation to be had

[stmoy]

There's a bunch of great conversation here! On the topic of animations...

It sounds like ElementAnimator is too much for animating Expander, and that ExpandTransition and CollapseTransition would suffice.

Agree that ElementAnimator is too much for animating Expander. It might work if everything was in an ItemsRepeater, but ElementAnimator doesn't work outside of ItemsRepeater yet so we'd need to figure that out.

I like the idea of having an ExpandTransition and CollapseTransition in theory, but we've gotten a ton of feedback that the Transition APIs are good in theory but less good in practice because they are not customizable, they are generally tightly coupled to the controls in which they are used, and I don't think they can be built in WinUI 2.x series since they rely on OS hooks. Since these specific transitions don't exist, I'd prefer to explore other options than adding to our collection of ThemeTransition APIs.

On top of all of that, the general area of "layout animations" where content moves as a result of new UI elements entering/growing/shrinking/leaving the page are not well supported in Xaml as a platform today. Fixing this will also require WinUI 3, but isn't on the immediate roadmap.

For Expander in particular, I think the proper course of action will likely end up being:

1. Hard-code the grow/shrink animation in the Expander code (and consider including an API to turn it off - though I don't personally think one is necessary)
2. Provide guidance to app developers about how to animate content around the Expander so that the content below the Expander slides down rather than "jumps" down

I don't think (2) can be solved generally without "layout animations" but can probably be worked around using RepositionThemeAnimation on the content below the Expander.

[ranjeshj]

@stmoy We could use PopInThemeAnimation for (1) if we wanted to go with the existing ones.

[kat-y]

This proposal has been approved for spec writing.

As part of discussion with the WinUI team, we determined that Expander could be scoped to support ExpandDirection for up/down expansion in V1. This covers the scenarios we've seen for Expander and lays groundwork to potentially add left/right expansion in the future.

Please feel encouraged to continue discussion here, and more detailed discussion will occur on the Spec and the associated PR once it's available. Would especially love to hear your thoughts on this open question:

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

[gabbybilka]

For InfoBar, I think I need to open a separate proposal to dive into what specifically it needs and how it can take advantage of this Expander control. Here's some of my first thoughts:

• An InfoBar needs to customize the header and content/pane of the Expander control. The InfoBar should show a "cut-off" message in the header when collapsed and a full message in the expanded content/pane when opened.
• An InfoBar doesn't have to allow truncation and the option should be there for the developer to choose the current wrapping behavior if needed via a "shouldTruncate" property.
• An InfoBar could/should "become" an Expander if the content no longer fits on a single line and shouldTruncate is set to true. Implementing this and understanding when exactly to add the expanding behavior is where it gets tricky 😊 MessageBar mitigates this via their isMultiline property but further thought needs to go into this area.

I think we can also look into other controls in WinUI currently that may benefit from this Expander behavior.

Some initial comps for truncating InfoBar:

For implementation, my initial thoughts are that an InfoBar should derive from an Expander and not be nested inside Expander's content. Thoughts?

[mdtauk]

I think we can also look into other controls in WinUI currently that may benefit from this Expander behavior.

Some initial comps for truncating InfoBar:

I think the Expander may need to be able to separate the Chevron Button from the Content being expanded.

Notifications do this

It would also allow the InformationBar control to integrate it's Expander.

If you do separate it, does that become a behaviour/property? So if you specify a UI Element or Button to this property, the Expander Header does not display it's Button?

For implementation, my initial thoughts are that an InfoBar should derive from an Expander and not be nested inside Expander's content. Thoughts?

If the Expander can't separate the Content and Header from the Toggle/Disclose Button - then that would require more work for the InformationBar to implement.

The Expander control should be as flexible as possible specifically for integrating into various other Controls going forward, as well as for use in the Windows Shell

[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 😄

[robloo]

There is a need in some cases to prevent the expander from expanding/collapsing. However, it is very difficult to implement this correctly with the current control even in WPF. In order to support this I propose adding two things:

1. PreviewExpanded/PreviewCollapsed events that allow cancelling the operation
2. A new property IsPinned could be added to pin or lock the expander in the current state until it is unpinned

[mdtauk]

Why is the expander using so much padding top and bottom?

and not closer in line with the ComboBox and DropDownButton controls?

[robloo]

Shouldn't this be closed?

[michael-hawker]

@robloo if it is, a follow-on issue for Left/Right support should be opened which is dependent on #546

[Jay-o-Way]

Is this still an issue ? /needinfo

[SnowyWreath]

Can we get an update on the roadmap for Left and Right ExpanderDirection? Windows Community Toolkit v8.0 was released yesterday, removing its Expander control because it is now part of WinUI. This feels premature, because the toolkit control offers Left/Right expansion.