Skip to main content

Choosing a layout panel

Avalonia offers a variety of layout panels that fulfil different UI roles. This guide helps you pick the best panel control for your desired layout strategy.

Decision flowchart​

  1. Do you need rows and columns with different sizes? Use Grid.
  2. Do you need a header, footer, or sidebar around the content area? Use DockPanel.
  3. Do you need items stacked in a single direction? Use StackPanel.
  4. Do you need items to wrap to the next line when space runs out? Use WrapPanel.
  5. Do you need items in a uniform grid of equal-sized cells? Use UniformGrid.
  6. Do you need to position items relative to each other? Use RelativePanel.
  7. Do you need pixel-precise absolute positioning? Use Canvas.
  8. Do you need to layer children on top of each other? Use Panel.

Quick comparison​

PanelArrangementAdapts to window sizeBest for
GridRows and columnsYesMost general-purpose layouts, forms, dashboards
DockPanelEdges (top, bottom, left, right) and fillYesApp shells with header, sidebar, and content area
StackPanelSingle line (vertical or horizontal)Partial (stretches perpendicular, scrolls along)Toolbars, menus, simple series of controls
WrapPanelSequential with line wrappingYesTag clouds, icon grids, responsive item collections
UniformGridEqual-sized cellsYesCalculator keypads, image galleries, dashboards with equal tiles
RelativePanelRelative to siblings or panel edgesYesAdaptive layouts that rearrange based on available space
CanvasAbsolute coordinatesNoDrawing surfaces, diagrams, custom overlays
PanelLayered on top of each otherYesOverlays, stacking visuals at the same position

Grid​

A versatile panel suitable for many common layouts. Define rows and columns with fixed, proportional (*), or automatic (Auto) sizing. Place children in specified target cells.

<Grid xmlns="https://github.com/avaloniaui"
      ColumnDefinitions="100,*"
      RowDefinitions="Auto,*"
      ShowGridLines="true">
    <TextBlock Grid.Row="0" Grid.Column="0" Text="Label" />
    <TextBox Grid.Row="0" Grid.Column="1" />
    <Button Grid.Row="1" Grid.Column="0" Grid.ColumnSpan="2" HorizontalAlignment="Center">
      Button spanning two columns
    </Button>
</Grid>
Preview
Loading Avalonia Preview...

Use when: You need a structured layout with rows and columns of varying sizes, such as a form, dashboard, or any layout that mixes fixed and flexible regions.

Avoid when: You need all children to be stacked in one direction (use StackPanel instead). You need all cells to be the same size (use UniformGrid instead). Also, Grid is heavier than simpler panels, so use a lighter panel type if the complexity of Grid isn't needed.

For more information, see the Grid page.

DockPanel​

Docks children to the edges of the panel. The last child fills the remaining space.

<DockPanel xmlns="https://github.com/avaloniaui">

    <Menu DockPanel.Dock="Top" Background="Gray">
      <MenuItem Header="_File" />
      <MenuItem Header="_Edit" />
    </Menu>

    <TextBlock DockPanel.Dock="Bottom" Background="Lime" Text="Ready" />

    <StackPanel DockPanel.Dock="Right" Width="100">
      <Button Content="Zoom in" />
      <Button Content="Zoom out" />
    </StackPanel>

    <ContentControl Background="Beige" />  <!-- fills remaining space -->

</DockPanel>
Preview
Loading Avalonia Preview...

Use when: You are building an app shell with a fixed header, footer, and/or sidebar around a central content area.

Avoid when: You need children to share space proportionally (use Grid instead). DockPanel gives priority to children declared earlier.

For more information, see the DockPanel page.

StackPanel​

Arranges children in a single line, either vertical (default) or horizontal. Children stretch to fill the perpendicular direction.

<StackPanel xmlns="https://github.com/avaloniaui"
            Spacing="8">
    <TextBlock Text="Name" />
    <TextBox />
    <TextBlock Text="Email" />
    <TextBox />
    <Button Content="Submit" HorizontalAlignment="Right" />
</StackPanel>
Preview
Loading Avalonia Preview...

Use when: You want a short, linear series of controls, such as a toolbar, settings form, or menu.

Avoid when: You want a long series of items that exceeds the available space. StackPanel gives children unlimited space, and does not trigger scrolling. Consider wrapping in a ScrollViewer, or using an ItemsControl with virtualization instead.

For more information, see the StackPanel page.

WrapPanel​

Lays out children left to right (or top to bottom), wrapping to a new line on reaching the edge.

<WrapPanel xmlns="https://github.com/avaloniaui" 
           ItemSpacing="8" LineSpacing="8">
    <Button Content="One" />
    <Button Content="Two" />
    <Button Content="Three" />
    <Button Content="Four" />
    <Button Content="Five" />
</WrapPanel>
Preview
Loading Avalonia Preview...

Use when: You want items to flow based on available space, like tags, thumbnails, or a responsive button bar.

Avoid when: You need items to align in a strict pattern. WrapPanel items on different lines are spaced independently and will not form neat columns.

For more information, see the WrapPanel page.

UniformGrid​

Divides the available space into equal cells. Children fill cells sequentially.

<UniformGrid xmlns="https://github.com/avaloniaui" 
             Columns="3">
    <Button Content="7" />
    <Button Content="8" />
    <Button Content="9" />
    <Button Content="4" />
    <Button Content="5" />
    <Button Content="6" />
    <Button Content="1" />
    <Button Content="2" />
    <Button Content="3" />
</UniformGrid>
Preview
Loading Avalonia Preview...

Use when: Every item should be the same size, such as a calculator keypad, color palette, or dashboard with equal tiles.

Avoid when: You need items of different sizes (use Grid instead).

For more information, see the UniformGrid page.

RelativePanel​

Positions children relative to sibling controls or panel edges using attached properties.

<RelativePanel xmlns="https://github.com/avaloniaui">
    <TextBlock Name="TitleText" Text="Title"
               RelativePanel.AlignTopWithPanel="True"
               RelativePanel.AlignLeftWithPanel="True" />
    <TextBox Name="SearchBox"
             RelativePanel.Below="TitleText"
             RelativePanel.AlignLeftWith="TitleText"
             RelativePanel.AlignRightWithPanel="True"
             Margin="0,8,0,0" />
    <Button Content="Search"
            RelativePanel.Below="SearchBox"
            RelativePanel.AlignRightWithPanel="True"
            Margin="0,8,0,0" />
</RelativePanel>
Preview
Loading Avalonia Preview...

Use when: You need to describe layout relationships between controls, e.g., "place this button below that text box and align it to the right edge". This is especially useful for adaptive layouts where you can change relationships based on available space.

Avoid when: A simpler panel can create your layout. RelativePanel is flexible but verbose. If your layout fits a Grid or StackPanel, use those instead.

For more information, see the RelativePanel page.

Canvas​

Places children at exact pixel coordinates using Canvas.Left, Canvas.Top, Canvas.Right, and Canvas.Bottom.

<Canvas xmlns="https://github.com/avaloniaui">
    <Ellipse Canvas.Left="50" Canvas.Top="30"
             Width="80" Height="80" Fill="Blue" />
    <Rectangle Canvas.Left="150" Canvas.Top="60"
               Width="100" Height="50" Fill="Red" />
</Canvas>
Preview
Loading Avalonia Preview...

Use when: You need absolute positioning for a drawing surface or a diagram. You want a drag-and-drop interface that places objects at specific coordinates.

Avoid when: You are building a standard application UI. Canvas does not adapt to window resizing, so content can be clipped or leave empty space if the window size changes.

For more information, see the Canvas page.

Panel​

A minimal container that layers children on top of each other, in declaration order. Use ZIndex to control which child appears on top.

<Panel xmlns="https://github.com/avaloniaui">
    <ContentControl Name="BG" Background="Gray" />
    <TextBlock Text="Overlay text"
                HorizontalAlignment="Center"
                VerticalAlignment="Center" />
</Panel>
Preview
Loading Avalonia Preview...

Use when: You want to overlay one control on top of another, such as a watermark over an image or a loading indicator over content.

Avoid when: You want children side-by-side or in a sequence.

For more information, see the Panel page.

Nesting panels​

For complex layouts, you can combine multiple panels. Nest panels within one another, and use the simplest panel at each level.

<DockPanel xmlns="https://github.com/avaloniaui">

    <!-- App shell: header + sidebar + content -->
    <Menu DockPanel.Dock="Top"
          Background="Gray">
      <MenuItem Header="_File" />
      <MenuItem Header="_Edit" />
    </Menu>

    <StackPanel DockPanel.Dock="Left"
                Width="100"
                Spacing="4"
                Background="Navy">
        <!-- Sidebar: vertical list of navigation items -->
        <Button Content="Home" />
        <Button Content="Settings" />
    </StackPanel>

    <Grid RowDefinitions="*,Auto">
        <!-- Content area: main content + status bar -->
        <ContentControl Grid.Row="0" />
        <TextBlock Grid.Row="1" Background="Lime" Text="Ready" />
    </Grid>

</DockPanel>
Preview
Loading Avalonia Preview...

Performance tips​

  • Prefer simpler panels when possible. StackPanel and Panel are lighter than Grid.
  • Avoid deeply nested panels. If you find yourself nesting more than three levels deep, consider whether a single Grid with the right row and column definitions could replace the entire tree.
  • For large scrollable lists, use ItemsRepeater or ListBox with virtualization instead of putting hundreds of controls in a StackPanel inside a ScrollViewer.

See also​

On this page