List Grouping

List grouping is a CSS utility for applying connected corner shapes to related direct children. It does not render a wrapper or impose layout, spacing, ARIA roles, or list semantics.

Add data-scope="list" data-part="container" to the container. Direct children opt in with data-list-group-item and declare a data-shape of rounded or square:

<section class="settings-list" data-scope="list" data-part="container">
  <ListItem title="Account" />
  <StatusRow data-list-group-item data-shape="rounded" />
  <article data-list-group-item data-shape="rounded">Last synced just now</article>
</section>

ListItem automatically carries the participant marker and its shape prop supplies data-shape. Other elements and components must provide both attributes explicitly.

Behavior

With the default tokens, rounded middle participants use an 8px radius and the first and last rounded participants use 24px outer corners. Square middle participants use 4px; square first and last participants use 4px on their inner corners and retain their own outer shape.

Only marked direct children participate. Headings, dividers, and other unmarked children do not affect first or last matching. Nested grouping containers form independent groups. The utility styles only participant roots, so custom components remain responsible for their internal surfaces and clipping.

When a container or participant marker is placed on a Vue component, its root must receive fallthrough attributes. A single-root component does this by default; components using inheritAttrs: false should forward $attrs to the intended root.

ListItem additionally adapts its active indicator to the resolved group shape.

Examples

Rounded and square

The same container contract supports rounded and square participants, including mixed custom roots.

Rounded

Custom status row

Square

Passive and custom participants

Interactive behavior is independent from grouping. Passive ListItem roots and user-owned elements participate using the same shape contract.

hard_driveStorage18 GB of 64 GB used

cloud_doneCloud backupCompleted 2 minutes ago

Non-participants and nested groups

Unmarked direct children are ignored, while a nested container calculates its own first and last participants.

Account

This unmarked note does not participate in first/last matching.

Nested group

Custom shapes

Set the grouping tokens on each container to tune its middle and outer corners without targeting participant internals.

Compact

Expressive

Styling

Set the following tokens on the grouping container.

Styling3

Preview

Token	Description
--md-list-group-item-first-child-shapeShape Fallback--dp(24)	Controls the block-start corner radius of the first direct rounded participant.
--md-list-group-item-last-child-shapeShape Fallback--dp(24)	Controls the block-end corner radius of the last direct rounded participant.
--md-list-group-item-shapeShape Fallbackrounded: var(--md-sys-shape-corner-small); square: var(--md-shape-compact)	Controls the base corner radius of direct grouping participants.