| -api-id | -api-type |
|---|---|
T:Microsoft.UI.Xaml.Controls.Grid |
winrt class |
Defines a flexible grid area that consists of columns and rows. Child elements of the Grid are measured and arranged according to their row/column assignments (set by using Grid.Row and Grid.Column attached properties) and other logic.
<Grid ...>
oneOrMoreUIElements
</Grid>
-or-
<Grid .../>Tip
For more info, design guidance, and code examples, see Layout panels.
Grid is a layout panel that supports arranging child elements in rows and columns.
You typically define layout behavior for a Grid in XAML by providing one or more RowDefinition elements as the value of Grid.RowDefinitions, and one or more ColumnDefinition elements as the value of Grid.ColumnDefinitions. Then, you apply the Grid.Row and Grid.Column attached properties to each of the element children of the Grid, to indicate which row/column combination is used to position that element within the parent Grid.
To set the height of rows and the width of columns, you set RowDefinition.Height for each RowDefinition and ColumnDefinition.Width for each ColumnDefinition. ColumnDefinition.Width and RowDefinition.Height are the respective content properties of ColumnDefinition and RowDefinition.
By default, each row or column divides layout space equally. You can change this behavior either by providing absolute pixel values, or a Star sizing that divides available space using a weighted factor. For more info on how to use Star sizing in a Grid, see Define layouts with XAML or GridLength. You also can use an Auto sizing that sizes to content.
Note that there are two ways to define a Grid. If you are simply defining rows and columns without using data binding or defining properties such as MinHeight or MaxWidth, you can use the following succinct syntax:
[!code-xamlGridSample1NewSyntax]
If you need to add more details in your Grid definition, such as providing a row's MaxHeight or using data binding in a row/column definition, you should use the original, full-fledged Grid syntax:
[!code-xamlGridSample1OldSyntax]
To indicate that an element child should span multiple rows or multiple columns in the Grid, you can apply the Grid.RowSpan or Grid.ColumnSpan attached properties to child elements of a Grid.
By default, a Grid contains one row and one column.
Setting the Margin property on the child elements in a Grid sets the distance between the element and its grid cell boundaries. The HorizontalAlignment and VerticalAlignment properties describe how the child element should be positioned within the grid cell. You can precisely position child elements of a Grid by using a combination of the Margin property and alignment properties. If you need even more control over the layout of individual child elements, consider using VariableSizedWrapGrid.
WrapGrid is another similar layout panel that has the benefit of better handling for content that's too wide, which might be clipped by a regular Grid depending on values of other layout properties.
An element in the first column that spans multiple rows can affect the height of each spanned row even if the first row has enough height to accommodate the element, and subsequent spanned rows would otherwise have a height of 0. For example, the second row in this Grid has its height set to 0, so the blue rectangle would not typically be visible. In this case, you might expect that the red ellipse would not affect the second row because the first row is tall enough to contain the ellipse. However, the Grid calculates the MinHeight of each row to be enough to accommodate the red ellipse, and then spans the element across the rows. As a result, the second row is given a MinHeight of 50, the red ellipse is centered in the 150px span, and half of the blue rectangle is visible in the second row.
Note
(This example uses an element that spans columns, but also applies to an element in the first column that spans multiple rows.)
[!code-xamlGridSample2]
Grid defines border properties that let you draw a border around the Grid without using an additional Border element. The properties are Grid.BorderBrush, Grid.BorderThickness, Grid.CornerRadius, and Grid.Padding.
<Grid BorderBrush="Red" BorderThickness="2" CornerRadius="10" Padding="12">
<TextBlock Text="Hello World!"/>
</Grid>Grid is the parent class for SwapChainPanel and SwapChainBackgroundPanel.
Grid is the host service class for several XAML attached properties. These attached properties enable child elements to report how they should be positioned in their Grid parent.
In order to support XAML processor access to the attached properties, and also to expose equivalent get and set operations to code, each XAML attached property has a pair of Get and Set accessor methods. Another way to get or set the value in code is to use the dependency property system, calling either GetValue or SetValue and passing the identifier field as the dependency property identifier.
| Attached property | Description |
|---|---|
| Column | Gets or sets the column alignment of an element when child layout is processed by a parent Grid layout container.
|
| ColumnSpan | Gets or sets a value that indicates the total number of columns that the element content spans within a parent Grid.
|
| Row | Gets or sets the row alignment of an element when child layout is processed by a parent Grid layout container.
|
| RowSpan | Gets or sets a value that indicates the total number of rows that the element content spans within a parent Grid.
|
Tip
For more info, design guidance, and code examples, see Layout panels.
[!div class="nextstepaction"] Open the WinUI 3 Gallery app and see the Grid in action
The WinUI 3 Gallery app includes interactive examples of most WinUI 3 controls, features, and functionality. Get the app from the Microsoft Store or get the source code on GitHub.
This XAML example shows how to design a layout by using a Grid.
[!code-xamlGridSample3]
[!code-csharpGridCsharpSample1]
Panel, Grid.Row, Grid.Column, Define layouts, Alignment, margin, and padding, Attached properties overview, Canvas, StackPanel, VariableSizedWrapGrid, WrapGrid, Controls list