Using ion-item-group

The MD3 theme uses the same inset-list structure as @rdlabo/ionic-theme-ios26, allowing one template to work across Ionic modes. When an ion-list uses inset="true", wrap its items in ion-item-group and keep ion-list-header outside the group.

The examples use framework-neutral Web Component markup. In React or Vue, use the equivalent component and property syntax.

<ion-list inset="true">
  <ion-list-header><ion-label>Connections</ion-label></ion-list-header>
  <ion-item-group>
    <ion-item>...</ion-item>
    <ion-item>...</ion-item>
  </ion-item-group>
</ion-list>

No wrapper is required for lists that do not use inset="true".

Check list structure with ESLint.

Why the wrapper is required

The shared structure keeps ion-list-header separate from the item surface. This matches the iOS 26 layout while allowing MD3 to style the same markup without platform-specific templates.

The theme therefore:

• makes the inset ion-list background transparent;
• applies the item surface to ion-item-group; and
• leaves ion-list-header outside that surface.

For two-line items and section-header groups, see Special markup.