Group box

GroupBox is a bordered box with a caption on it, holding controls that belong together.

Two parts: Legend holds the words and Content holds the controls. Content is the content host, so a nested tag lands inside without being told to, and the legend hides itself when Label is null.

The container half of doc 49 § 7.1's fourth rank. LabeledContent is the row; this is what a set of rows goes inside.

⚠ Card and Panel already draw this picture, and they are exempt from the accessibility sweep for a good reason: they are layout. A tree that announced every bordered box would read a four-field form as thirty nested groups, which is how an accessibility tree becomes complete and useless. That is the right decision for a box that happens to have a border, and the wrong one for a box whose whole purpose is to say these belong together.

⚠ The role is what this type is, not the border. A GroupBox reports AccessibleRole.Group — HTML's <fieldset> — named by its legend, so a reader entering it hears the caption and then the controls. A Card with a TextBlock in its header draws exactly the same thing and says nothing at all: those words are read when a reader walks past them and never again, and somebody who tabbed straight into the third field never walked past them.

Reach for Panel or Card when the box is arrangement. Reach for this one when a person who cannot see the border still needs to know the controls are one question.

group.Add<NumericInput>() is the same call: Add<T> parents on the control's content host, which is where a nested tag goes in markup, so C# and markup land in the same place however they are written. ⚠ Until #1425 it did not, and group.Add<T>() put the field beside the legend, outside the group.

The caption is one property and one copy of the words. Label writes the legend and is also what the group answers as its accessible name, so there is no relation to keep in step and nothing to forget:

⚠ An unnamed group is still a group. Leaving Label unset hides the legend and leaves the role where it is; the role never moves under a property, because nothing could rely on one that did. A group with nothing to say is a caller who wanted Panel.

A settings section with named fields inside it. The group is the context and the row is the name, and they compose — the field is announced as "Resolution, in the Shadows group" rather than as either one alone.

A set of alternatives. A radio group inside a group box is the arrangement <fieldset> was invented for: the question is on the box, the answers are inside it, and neither has to repeat the other.

⚠ In markup a RadioGroup is filled through ref and OnComposed rather than by nesting — it has no content host — so this one is C#. The group box itself nests either way.

Styling it. The tag draws the border and the legend is a bare part, so a sheet can move either without the control knowing:

• Labeled content — the row that names one field, and the relations it writes.
• Form — what submits the fields in a group, and refuses while one is wrong.
• Section — a titled part of a page, announced as a landmark rather than a group.
• Markup panels — Panel, Card and the boxes that are deliberately not announced.
• Accessibility — roles, names and relations, and what a sweep holds them to.