Add WrapPanel API Spec based on Windows Community Toolkit (WCT) #10858

michael-hawker · 2025-10-28T00:17:35Z

This PR adds the dev and functional spec for WinUI WrapPanel (from Windows Community Toolkit).

Community members can provide feedback by commenting directly on the PR, or through a code suggestion with GitHub tools.
Feedback should be constructive and specific, addressing potential use cases, design concerns, and functionality.

This PR will be open for feedback for a month: October 27th – November 27th
For more info on the public api review process: https://aka.ms/winappsdk/api-specs-review

…ol for Public Review

Poker-sang · 2025-10-29T04:32:24Z

How about changing HorizontalSpacing and VerticalSpacing to ItemSpacing and LineSpacing? This is consistent with the naming precedent in LinedFlowLayout and better suits users' intuition.

mdtauk · 2025-10-29T04:45:40Z

How about changing HorizontalSpacing and VerticalSpacing to ItemSpacing and LineSpacing? This is consistent with the naming precedent in LinedFlowLayout and better suits users' intuition.

Not sure I agree, as because "Lined" is in the name, the Line spacing makes more sense, and has context which does not exist with a wrap panel.

mdtauk · 2025-10-29T04:50:15Z

Is there scope to allow different behaviours for how items are placed?

With the Files app, we have come across an issue where each row uses the calculated height from only the first item in the panel, where we would like each row to take it's height from the tallest item that wraps into it?

I know this would likely be considered a breaking change, but if it were a new property that could be toggled/switched, it would make the control more flexible. File Explorer's grid view uses this behaviour.

File Explorer

zxbmmmmmmmmm · 2025-10-29T05:03:30Z

How about changing HorizontalSpacing and VerticalSpacing to ItemSpacing and LineSpacing? This is consistent with the naming precedent in LinedFlowLayout and better suits users' intuition.

Not sure I agree, as because "Lined" is in the name, the Line spacing makes more sense, and has context which does not exist with a wrap panel.

This is discussed previously in AvaloniaUI/Avalonia#18079. I think ItemSpacing/LineSpacing can avoid user confusion caused by different Orientation of wrap panel.

mdtauk · 2025-10-29T05:10:15Z

How about changing HorizontalSpacing and VerticalSpacing to ItemSpacing and LineSpacing? This is consistent with the naming precedent in LinedFlowLayout and better suits users' intuition.

Not sure I agree, as because "Lined" is in the name, the Line spacing makes more sense, and has context which does not exist with a wrap panel.

This is discussed previously in AvaloniaUI/Avalonia#18079. I think ItemSpacing/LineSpacing can avoid user confusion caused by different Orientation of wrap panel.

You could do maybe Row spacing, and Item spacing, which may make sense, but HorizontalSpacing and VerticalSpacing is consistent with many other controls, and should still be relevant regardless of orientation.

You could also have ItemHorizontalSpacing and ItemVerticalSpacing, which should also be agnostic regardless of the panel's Orientation.

Poker-sang · 2025-10-29T05:36:35Z

You could do maybe Row spacing, and Item spacing, which may make sense, but HorizontalSpacing and VerticalSpacing is consistent with many other controls, and should still be relevant regardless of orientation.

You could also have ItemHorizontalSpacing and ItemVerticalSpacing, which should also be agnostic regardless of the panel's Orientation.

@mdtauk RowSpacing, and ItemSpacing, make more sense than H/V Spacing, but not as good as LineSpacing.

If you set Orientation to Horizontal, the Line is a Column.

And ItemHorizontalSpacing and ItemVerticalSpacing is a even worse naming than H/V spacing.

First, it's tied to direction, causing confusion when switching Orientation. Second, the word Item does not make any sense; the spacing of a Line is not the spacing of an Item, which adds to the confusion. I'm sorry, but I completely disagree with you.

Poker-sang · 2025-10-29T05:50:50Z

This is LinedFlowLayout. Doesn't it look exactly like WrapPanel?

michael-hawker · 2025-10-29T10:48:44Z

Is there scope to allow different behaviours for how items are placed?

With the Files app, we have come across an issue where each row uses the calculated height from only the first item in the panel, where we would like each row to take it's height from the tallest item that wraps into it?

I know this would likely be considered a breaking change, but if it were a new property that could be toggled/switched, it would make the control more flexible. File Explorer's grid view uses this behaviour.

@mdtauk the current behavior of the WrapPanel (which is the same as it is in the Windows Community Toolkit) is that each row's height is calculated from the largest item in that row. You can see that with the random image sizes in the sample gallery:

So, I think that would cover your scenario? Unless I'm misunderstanding. But it should be called out within the spec somewhere on these expectations.

michael-hawker · 2025-10-29T10:49:44Z

@zxbmmmmmmmmm thanks to the link to the Avalonia discussion, that's useful context. I'll take a look.

mdtauk · 2025-11-05T18:05:24Z

Is there scope to allow different behaviours for how items are placed?
With the Files app, we have come across an issue where each row uses the calculated height from only the first item in the panel, where we would like each row to take it's height from the tallest item that wraps into it?
I know this would likely be considered a breaking change, but if it were a new property that could be toggled/switched, it would make the control more flexible. File Explorer's grid view uses this behaviour.

@mdtauk the current behavior of the WrapPanel (which is the same as it is in the Windows Community Toolkit) is that each row's height is calculated from the largest item in that row. You can see that with the random image sizes in the sample gallery:
So, I think that would cover your scenario? Unless I'm misunderstanding. But it should be called out within the spec somewhere on these expectations.

Can the items stretch to match the height of the tallest item, to fill the "row height"?

roxk · 2025-11-06T09:11:28Z

Is there scope to allow different behaviours for how items are placed?
With the Files app, we have come across an issue where each row uses the calculated height from only the first item in the panel, where we would like each row to take it's height from the tallest item that wraps into it?
I know this would likely be considered a breaking change, but if it were a new property that could be toggled/switched, it would make the control more flexible. File Explorer's grid view uses this behaviour.

@mdtauk the current behavior of the WrapPanel (which is the same as it is in the Windows Community Toolkit) is that each row's height is calculated from the largest item in that row. You can see that with the random image sizes in the sample gallery:

So, I think that would cover your scenario? Unless I'm misunderstanding. But it should be called out within the spec somewhere on these expectations.

Can the items stretch to match the height of the tallest item, to fill the "row height"?

IMO a more complete version of this ask is: WrapPanel should respect HorizontalAlignment and VerticalAlignment where applicable. Filling row height in this case would mean setting a horizontal wrap panel's child's VerticalAlignment="Stretch"

specs/WCT/Primitives/WrapPanel.md

… review meeting

michael-hawker · 2025-11-23T07:32:01Z

Thanks @neerajmsgithub for the review, I was a bit confused at first until I just referenced existing similar classes in the main idl file (src\dxaml\xcp\dxaml\idl\winrt\controls\microsoft.ui.xaml.controls.controls.idl); it was a good reference.

Also, for future reference, you can make suggestions directly as edits that I could accept in the file with this toolbar button:

That'll also allow me to easily credit your account for the suggestions within the commit.

specs/WCT/Primitives/WrapPanel.md

Co-authored-by: neerajmsgithub <[email protected]>

kmahone · 2025-11-24T21:08:28Z

specs/WCT/Primitives/WrapPanel.md

+![WrapPanel example layout](images/layout-panel-wrap-panel.png)
+
+In a WrapPanel, if a child element's size is not set explicitly, it will be given the minimal amount 
+of space for layout. In this example, the size of the rectangles are explicitly set, if the 


We should clarify that it is not required that every element has an explicit Width and Height set on it. A Button with some Content would render at the minimal size required to display that Button. The text as given right now makes it sounds like you MUST set an explicit Width and Height on every element in the WrapPanel.

Thanks; "minimal amount" was confusing as well. It's the "minimal size for the element" ?

Discussion: Clarify "minimal size" term. Wrap panel doesn't enforce any sizing.

Recommend: Draw analogy with auto.

Is this the element's sort of "natural size", the size that would be used by RowDefinition Height=Auto?

kmahone · 2025-11-24T21:18:37Z

specs/WCT/Primitives/WrapPanel.md

+The WrapPanel is a layout panel that arranges child elements in a sequential position from left to right, 
+items overflowing the line will break to the next line automatically at the edge of the containing panel. 
+
+![WrapPanel example layout](images/WrapPanel.png)


Thanks for including images. It makes understanding the text much easier.

One suggestion: Show some images of heterogeneous elements of different sizes. That will demonstrate the usefulness of WrapPanel. With the current images, it is not immediately obvious why one would use WrapPanel over Grid.

Example image for now, does it help to have it be practical example like this, or would it be better to use the colored rectangles?

One of the main differences with Grid, is that a Grid is very rigid and fixed and requires things like VisualStateManager and manipulation of attached properties of the elements within it to adapt to different sizes when your app size is changed. A WrapPanel adapts automatically and is commonly used for any small-medium sized collection of things which need to just flow with a document-style layout.

Discussion: Should remove "remove" text?

Recommend: Remove text from "Remove" from image.

jonwis · 2025-11-25T18:59:03Z

specs/WCT/Primitives/WrapPanel.md

+![WrapPanel example layout](images/layout-panel-wrap-panel.png)
+
+In a WrapPanel, if a child element's size is not set explicitly, it will be given the minimal amount 
+of space for layout. In this example, the size of the rectangles are explicitly set, if the 


Thanks; "minimal amount" was confusing as well. It's the "minimal size for the element" ?

jonwis · 2025-11-25T18:59:52Z

specs/WCT/Primitives/WrapPanel.md

+
+## WrapPanel class
+
+The WrapPanel is a layout panel that arranges child elements in a sequential position from left to right, 


Is there a flag for "right to left" layout for languages where that's the natural direction?

That's handled implicitly by the framework, as we inherit from Panel which is a FrameworkElement with FlowDirection.

And then toggling flow direction:

No change required.

jonwis · 2025-11-25T19:07:55Z

specs/WCT/Primitives/WrapPanel.md

+      StretchChild StretchChild;
+      Double VerticalSpacing;
+
+      static Microsoft.UI.Xaml.DependencyProperty HorizontalSpacingProperty { get; };


Let's say I want to have a 6 items in my panel. They're all buttons whose minimum size is 30. My wrap panel is autoresized to be width 360 (2x the required size to display all six buttons in a row.) With StretchChild=Last, I see (for widths, in a single row) 30, 30, 30, 30, 30, 210.

Is there a way to have all the items in the row expand to fit equal amounts, so I'd see 60, 60, 60, 60, 60, 60? Or if my width was 240, have it produce {60, 60, 60, 60},{120, 120}?

We have an EqualPanel as a separate base panel for the Segmented control in the Toolkit which is more the first scenario of evenly spacing elements across the available size, but it doesn't handle wrapping. Your second scenario is kind of a combination of both, but I would imagine instead be {80, 80, 80},{80, 80, 80}. The difference with the EqualPanel is its enforcing the size on the child, where the WrapPanel does not and adapts to the measure provided by its children.

We don't expose the EqualPanel as a general panel at the moment in the Toolkit, but I would think your scenarios here would be an element of that panel where we'd investigate allowing it to wrap if constrained by a max boundary (e.g. Width if Horizontal). The question of how to distribute space and handle a row beyond the first in those scenarios seems like a tricky one though.

For historical context on why this property/behavior of StretchChild was added (specifically for Last) was for the TokenizingTextBox where there was a series of some number of tokens in the box, and then we'd want the final input box to take up the remaining available space. We just made it a enum for future proofing for further scenarios, but hadn't encountered any worth investigating in the last few years.

Example of StretchChild=Last from the TokenizingTextBox in the WCT Gallery.

Discussion: Should panel handle layout like distribute proportionally? Do we need more control on how layout is handled in wrap panel? Should wrap panel cover those layout cases?

Current behavior is filling from left to right and wrap when required based on size. It is simple implementation and want to keep it that way.

No feature change required.

oldnewthing · 2025-11-26T16:29:34Z

specs/WCT/Primitives/WrapPanel.md

+      static Microsoft.UI.Xaml.DependencyProperty VerticalSpacingProperty { get; };
+  }
+
+  enum StretchChild


Maybe StretchChildren?

StretchChildren.None
StretchChildren.Last
StretchChildren.Proportional (possible future)

Also, this stretches only in the layout direction?

Discussion: None means don't stretch any children. Can it be seen as extra space distribution algorithm?

Recommend: Change to StretchChildren.

neerajmsgithub · 2025-11-26T16:09:19Z

specs/WCT/Primitives/WrapPanel.md

+![WrapPanel example layout](images/layout-panel-wrap-panel.png)
+
+In a WrapPanel, if a child element's size is not set explicitly, it will be given the minimal amount 
+of space for layout. In this example, the size of the rectangles are explicitly set, if the 


Discussion: Clarify "minimal size" term. Wrap panel doesn't enforce any sizing.

Recommend: Draw analogy with auto.

neerajmsgithub · 2025-11-26T16:10:41Z

specs/WCT/Primitives/WrapPanel.md

+
+## WrapPanel class
+
+The WrapPanel is a layout panel that arranges child elements in a sequential position from left to right, 


No change required.

neerajmsgithub · 2025-11-26T16:12:45Z

specs/WCT/Primitives/WrapPanel.md

+The WrapPanel is a layout panel that arranges child elements in a sequential position from left to right, 
+items overflowing the line will break to the next line automatically at the edge of the containing panel. 
+
+![WrapPanel example layout](images/WrapPanel.png)


Discussion: Should remove "remove" text?

Recommend: Remove text from "Remove" from image.

neerajmsgithub · 2025-11-26T16:22:03Z

specs/WCT/Primitives/WrapPanel.md

+then wraps the Green box around to the next line due to the Width constraint on the WrapPanel:
+
+```xml
+    <controls:WrapPanel Width="132" HorizontalSpacing="16">


Recommend: Add boxes with text may be alphabets to highlight size impact.

neerajmsgithub · 2025-11-26T16:23:46Z

specs/WCT/Primitives/WrapPanel.md

+      StretchChild StretchChild;
+      Double VerticalSpacing;
+
+      static Microsoft.UI.Xaml.DependencyProperty HorizontalSpacingProperty { get; };


Discussion: Should panel handle layout like distribute proportionally? Do we need more control on how layout is handled in wrap panel? Should wrap panel cover those layout cases?

Current behavior is filling from left to right and wrap when required based on size. It is simple implementation and want to keep it that way.

No feature change required.

neerajmsgithub · 2025-11-26T16:33:22Z

specs/WCT/Primitives/WrapPanel.md

+      static Microsoft.UI.Xaml.DependencyProperty OrientationProperty { get; };
+      static Microsoft.UI.Xaml.DependencyProperty PaddingProperty { get; };
+      static Microsoft.UI.Xaml.DependencyProperty StretchChildProperty { get; };
+      static Microsoft.UI.Xaml.DependencyProperty VerticalSpacingProperty { get; };


Discussion: Property name should be row/col spacing or horizontal/vertical spacing, line item spacing?

Flex calls it row/col gap.

Consider: Line spacing and item spacing is better choice.

neerajmsgithub · 2025-11-26T16:37:28Z

specs/WCT/Primitives/WrapPanel.md

+      static Microsoft.UI.Xaml.DependencyProperty VerticalSpacingProperty { get; };
+  }
+
+  enum StretchChild


Discussion: None means don't stretch any children. Can it be seen as extra space distribution algorithm?

Recommend: Change to StretchChildren.

Add WrapPanel API Spec based on Windows Community Toolkit (WCT) contr…

79800c9

…ol for Public Review

michael-hawker added this to API Specs Review Oct 28, 2025

michael-hawker moved this to API Review - Gathering Feedback in API Specs Review Oct 28, 2025

michael-hawker self-assigned this Oct 28, 2025

microsoft-github-policy-service bot added the needs-triage Issue needs to be triaged by the area owners label Oct 28, 2025

michael-hawker mentioned this pull request Oct 28, 2025

New row not created for last child in WrapPanel when StretchChild=Last CommunityToolkit/Windows#743

Open

michael-hawker added SpecInReview and removed needs-triage Issue needs to be triaged by the area owners labels Oct 30, 2025

neerajmsgithub reviewed Nov 19, 2025

View reviewed changes

specs/WCT/Primitives/WrapPanel.md Show resolved Hide resolved

Apply all IDL comments for API details from initial review before API…

2a74aae

… review meeting

neerajmsgithub reviewed Nov 24, 2025

View reviewed changes

specs/WCT/Primitives/WrapPanel.md Outdated Show resolved Hide resolved

Update specs/WCT/Primitives/WrapPanel.md

58ebcc7

Co-authored-by: neerajmsgithub <[email protected]>

kmahone reviewed Nov 24, 2025

View reviewed changes

jonwis reviewed Nov 25, 2025

View reviewed changes

oldnewthing reviewed Nov 26, 2025

View reviewed changes

neerajmsgithub reviewed Nov 26, 2025

View reviewed changes


		## WrapPanel class

		The WrapPanel is a layout panel that arranges child elements in a sequential position from left to right,

Add WrapPanel API Spec based on Windows Community Toolkit (WCT) #10858

Are you sure you want to change the base?

Add WrapPanel API Spec based on Windows Community Toolkit (WCT) #10858

Uh oh!

Conversation

michael-hawker commented Oct 28, 2025

Uh oh!

Poker-sang commented Oct 29, 2025

Uh oh!

mdtauk commented Oct 29, 2025

Uh oh!

mdtauk commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zxbmmmmmmmmm commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mdtauk commented Oct 29, 2025

Uh oh!

Poker-sang commented Oct 29, 2025

Uh oh!

Poker-sang commented Oct 29, 2025

Uh oh!

michael-hawker commented Oct 29, 2025

Uh oh!

michael-hawker commented Oct 29, 2025

Uh oh!

mdtauk commented Nov 5, 2025

Uh oh!

roxk commented Nov 6, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

michael-hawker commented Nov 23, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

mdtauk commented Oct 29, 2025 •

edited

Loading

zxbmmmmmmmmm commented Oct 29, 2025 •

edited

Loading