GroupBox Display

The header names the group for the keyboard and screen readers

GroupBox derives from HeaderedContentControl. To UI Automation it is a Group whose name is the header: a GroupBox with the header “Personal information” was reported under that name. Write headers that make sense read on their own, because screen readers announce them as the group’s name.

The header also takes part in keyboard access. A string header is shown with access keys recognized, so Header="_Name" made N an access key. Processing that access key with AccessKeyManager.ProcessKey moved the focus into the group, to the first TextBox of the content, not to the header; a physical Alt+N was not measured. Give the header an access key so the user can jump into the group with the keyboard.

What the header can show

With a null header, HasHeader, which is read-only, was False and the header area was 0 high. A string with a line break is shown on two lines: the header was 15.96 high for one line and 31.92 for two, so no TextBlock is needed for that.

HeaderStringFormat formats the header, for example to build “Items (12)” from a count. With "Header={0}.", the header HEADER was shown as Header=HEADER.. It applies only to headers that are not elements: with a TextBlock as the header, the text stayed HEADER.

The border, the padding, and what reaches the content

By default the border (BorderBrush and BorderThickness) is 1 wide in #FFD5DFE5, and Padding is 0. Padding works in the default template: with Padding="20", the content moved down by 20. Content is a single child inside the border; to put several controls in a group, use a panel as the content.

The font properties and Foreground reach the text of both the header and the content: FontSize="20" set on the GroupBox made both the header’s text and a TextBlock in the content 20. Background fills the area inside the border, starting at the middle of the header: in a GroupBox whose header was 1 to 27.6 from the top, the painted area started at 13.8. The top half of the header stays outside it. The content lies inside that area, so the background shows behind it.

The header, padding, inherited properties, and the access key. Measured on .NET 10 / Windows 11.

Trying it in the demo app

The GroupBox page of the demo app has sections for the header, HeaderStringFormat, the content, and the Control properties Padding, the font properties, Background, Foreground, and the border. The header section turns an empty text box into null. The “Show Code” link under each section displays its XAML. The following XAML is the HeaderStringFormat section (GroupBoxUsageControl.xaml), with the styles and the surrounding GroupBoxes left out and the namespace declarations added:

<StackPanel xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
            xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
  <TextBox x:Name="HeaderForHeaderStringFormatTextBox" Text="HEADER" />

  <GroupBox x:Name="HeaderStringFormatGroupBox"
            Header="{Binding Text, ElementName=HeaderForHeaderStringFormatTextBox}"
            HeaderStringFormat="Header={0}." />
</StackPanel>

Related controls and articles

• Expander — a header and content that the user can fold away.
• Label — also shows its text with access keys recognized.
• Grid — a common content of a GroupBox, to lay out labels and fields.

Source code and how it was measured

Every behavior on this page was measured by running it on .NET 10 / Windows 11, using GroupBoxDemoScene in this site’s screenshot tool. The header was read from the text element in the template’s header presenter. The access key was processed by calling AccessKeyManager.ProcessKey, which processes the given access key as if its key-down had been passed to the access key manager; this is an API call, not a physical Alt+key press. Positions are measured from the GroupBox’s top-left corner, and sizes are the values on the measuring machine.

View GroupBox source code on GitHub →