Skip to main content

GroupBox

The GroupBox control visually groups related content under a header label, surrounded by a border. The header text overlaps the top edge of the border, creating the classic "group box" appearance familiar from desktop UI frameworks.

GroupBox extends HeaderedContentControl, so it supports a Header (displayed at the top of the border) and a single Content child.

Common use cases​

Use a GroupBox when you need to:

  • Organize form fields into logical sections (for example, "Personal Details" and "Billing Address").
  • Visually separate groups of related options such as checkboxes or radio buttons.
  • Add a labeled frame around a section of your UI so that the purpose of the grouped controls is immediately clear.

Useful properties​

You will probably use these properties most often:

PropertyDescription
HeaderThe text or content displayed at the top of the border.
ContentThe child control or layout hosted inside the group box.
BorderBrushThe color of the surrounding border.
BorderThicknessThe thickness of the surrounding border.
CornerRadiusThe radius of the border's corners.
PaddingThe spacing between the border and the content.

Example​

This example creates two group boxes to organize a form:

<StackPanel xmlns="https://github.com/avaloniaui"
            Spacing="16" Margin="16">
  <GroupBox Header="Personal Details">
    <StackPanel Spacing="8">
      <TextBox PlaceholderText="First name" />
      <TextBox PlaceholderText="Last name" />
      <TextBox PlaceholderText="Email" />
    </StackPanel>
  </GroupBox>
  <GroupBox Header="Preferences">
    <StackPanel Spacing="8">
      <CheckBox Content="Receive notifications" />
      <CheckBox Content="Dark mode" />
    </StackPanel>
  </GroupBox>
</StackPanel>
Preview
Loading Avalonia Preview...

Custom header content​

The Header property accepts any content, not just text. You can use it to display icons, formatted text, or any other control:

<GroupBox>
  <GroupBox.Header>
    <StackPanel Orientation="Horizontal" Spacing="6">
      <PathIcon Data="{StaticResource SettingsIcon}" />
      <TextBlock Text="Advanced Settings" FontWeight="Bold" />
    </StackPanel>
  </GroupBox.Header>
  <StackPanel Spacing="8">
    <CheckBox Content="Enable logging" />
    <CheckBox Content="Verbose output" />
  </StackPanel>
</GroupBox>

Data binding the header​

You can bind the Header property to a view-model property, which is useful when the section label needs to update at runtime:

<GroupBox Header="{Binding SectionTitle}">
  <TextBlock Text="{Binding SectionContent}" />
</GroupBox>
public class MyViewModel : ViewModelBase
{
    private string _sectionTitle = "Details";

    public string SectionTitle
    {
        get => _sectionTitle;
        set => this.RaiseAndSetIfChanged(ref _sectionTitle, value);
    }
}

Nesting group boxes​

You can nest GroupBox controls inside each other to create sub-sections. Keep nesting shallow (one or two levels) to avoid cluttering your layout:

<GroupBox Header="Account">
  <StackPanel Spacing="12">
    <GroupBox Header="Login credentials">
      <StackPanel Spacing="8">
        <TextBox PlaceholderText="Username" />
        <TextBox PlaceholderText="Password" PasswordChar="*" />
      </StackPanel>
    </GroupBox>
    <GroupBox Header="Profile">
      <StackPanel Spacing="8">
        <TextBox PlaceholderText="Display name" />
        <TextBox PlaceholderText="Bio" />
      </StackPanel>
    </GroupBox>
  </StackPanel>
</GroupBox>

Styling​

You can customize the GroupBox appearance through theme resources:

ResourceDefaultDescription
GroupBoxPadding4Internal padding around the content.
GroupBoxHeaderFontSize16Font size of the header text.
GroupBoxHeaderMargin0,4,0,12Margin around the header.
GroupBoxBorderThickness1Thickness of the surrounding border.
GroupBoxBackgroundTransparentBackground fill of the content area.
GroupBoxBorderBrushSystemControlForegroundBaseMediumBrushColor of the border.
GroupBoxHeaderForegroundSystemBaseHighColorColor of the header text.

See also​

On this page