CSS Shadow Parts Guidelines

_{<b>TABLE OF CONTENTS</b>}

• Definitions
• Scope
• General Guidelines
• Standard Parts
• Specialized Parts
• Documentation

Definitions

CSS Shadow Parts: The CSS shadow parts module defines the ::part() pseudo-element that can be set on a shadow host. Using this pseudo-element, you can enable shadow hosts to expose the selected element in the shadow tree to the outside page for styling purposes. ¹

Scope

Ionic Framework components that use Shadow DOM expose CSS Shadow Parts to enable custom styling by end users.

This document establishes a standardized naming convention for CSS Shadow Parts in Ionic Framework components.

General Guidelines

1. Attempt to use standard parts first: Use native, wrapper, inner, container, and content wherever they apply before inventing new names.
2. Use semantic, kebab-case names: Choose descriptive names that communicate the role of the element (for example, detail-icon, supporting-text).
3. Reuse names for the same concept: Use the same part name across components when the element serves the same role (for example, backdrop, handle, label).

Standard Parts

Name parts by what the element does, not where it appears. Ask what role the element plays:

The following examples show the correct usage for the standard parts.

native

What it does: The element the user directly interacts with - the native button, anchor, or form control (e.g. <button>, <a>, <textarea>, <input>).

• Use when: The element receives click/focus/input from the user.
• Examples: ion-item, ion-button, ion-back-button, ion-segment-button.

ion-item - the interactive element is the <button>, <a>, or <div> (TagType):

const TagType = clickable ? (href === undefined ? 'button' : 'a') : ('div' as any);

return (
  <Host>
    <TagType class="item-native" part="native">
      <slot name="start"></slot>
      <div class="item-inner" part="inner">
        <div class="input-wrapper" part="container">
          <slot></slot>
        </div>
        <slot name="end"></slot>
      </div>
    </TagType>
  </Host>
);

wrapper

What it does: The HTML <label> element that wraps the entire form control. Clicking anywhere on it focuses the control.

• Use when: The element is the <label> that wraps the form control.
• Examples: ion-select.

ion-select - the <label> has part="wrapper":

<label class="select-wrapper" part="wrapper">
  <div class="select-start" part="start">
    <slot name="start"></slot>
  </div>
  <div class="select-control" part="control">
    {this.renderLabel()}
    <div class="native-wrapper" part="container">...</div>
  </div>
  <div class="select-end" part="end">
    <slot name="end"></slot>
  </div>
</label>

The start and end slots are wrapped in their own containers rather than sitting directly inside the label, so they can be styled and measured independently of the control.

inner

What it does: The inner layout wrapper around the main content. It may wrap only the default slot (e.g. ion-list-header), or it may wrap a container and the slot(s) (e.g. start, end) that sit alongside the main content. In ion-item and ion-item-divider, the start slot is a sibling of this element.

• Use when: The element is the inner layout wrapper (with or without a separate container and start/end slots).
• Examples: ion-list-header (.list-header-inner wraps only the default slot), ion-item (.item-inner), ion-item-divider (.item-divider-inner), ion-item-option (.item-option-inner).

ion-list-header - .list-header-inner wraps only the default slot (no container, no start/end slots):

<div class="list-header-inner" part="inner">
  <slot></slot>
</div>

ion-item - .item-inner wraps the container and end slot (start slot is a sibling):

<slot name="start"></slot>
<div class="item-inner" part="inner">
  <div class="input-wrapper" part="container">
    <slot></slot>
  </div>
  <slot name="end"></slot>
</div>

ion-item-divider - .item-divider-inner wraps the container and end slot (start slot is a sibling):

<slot name="start"></slot>
<div class="item-divider-inner" part="inner">
  <div class="item-divider-wrapper" part="container">
    <slot></slot>
  </div>
  <slot name="end"></slot>
</div>

container

What it does: Wraps the main content - either the default slot (for item-like components) or the native control and its immediate content (for form controls like select, textarea).

• Use when: The element wraps the default slot, or wraps the native control (and any immediate content like listbox or slots inside it).
• Don’t use when: The element is the main content area of an overlay (use content instead).
• Examples: ion-item (.input-wrapper around default slot), ion-item-divider (.item-divider-wrapper), ion-select (.native-wrapper around select text + listbox).

From the examples above:

ion-item - .input-wrapper wraps the default <slot>:

<slot name="start"></slot>
<div class="item-inner" part="inner">
  <div class="input-wrapper" part="container">
    <slot></slot>
  </div>
  <slot name="end"></slot>
</div>

ion-select - .native-wrapper wraps the select text and listbox:

<div class="select-control" part="control">
  {this.renderLabel()}
  <div class="native-wrapper" part="container">
    {this.renderSelectText()}
    {this.renderListbox()}
  </div>
</div>

control

What it does: Groups the label and the native control so they lay out together, separately from the start and end slot containers on either side of them.

• Use when: A form control needs the label and the native control positioned as a unit, for example so that label-placement can switch between a row and a column without moving the slots.
• Don't use when: The element also wraps the start/end slots (use inner instead).
• Examples: ion-select (.select-control).

ion-select - .select-control groups the label and the native wrapper, with the slots as siblings:

<div class="select-start" part="start">
  <slot name="start"></slot>
</div>
<div class="select-control" part="control">
  {this.renderLabel()}
  <div class="native-wrapper" part="container">...</div>
</div>
<div class="select-end" part="end">
  <slot name="end"></slot>
</div>

content

What it does: The main user-content area of an overlay or the primary content region (e.g. modal body, toolbar’s main slot).

• Use when: The element is the primary content area where users see the main content (overlay body, or primary slot inside something like a toolbar).
• Examples: ion-modal, ion-popover, ion-accordion, ion-toolbar (the div that wraps the default slot inside the toolbar container).

ion-modal - content wraps the default <slot> which is the primary content:

<div class="modal-content" part="content">
  <slot></slot>
</div>

ion-toolbar - content wraps the default <slot> which is the primary content:

<div class="toolbar-container" part="container">
  <slot name="start"></slot>
  <slot name="secondary"></slot>
  <div class="toolbar-content" part="content">
    <slot></slot>
  </div>
  <slot name="primary"></slot>
  <slot name="end"></slot>
</div>

Specialized Parts

Components may also expose specialized parts for specific elements. The following parts are reused across multiple components:

When to create new specialized parts:

• Use standard parts (native, wrapper, inner, container, content) when they apply
• Reuse existing specialized parts (listed above) when they match the element's role
• Create component-specific specialized parts for elements that don't fit standard patterns or existing specialized parts
• Use descriptive, semantic names (e.g., header, text, arrow, scroll for component-specific elements)

Documentation

Shadow parts must be documented in the component's JSDoc comments using the @part tag. The following example demonstrates the proper documentation format:

/**
 * @part native - The native HTML button, anchor or div element that wraps all child elements.
 * @part inner - The inner wrapper element that arranges the item content.
 * @part container - The wrapper element that contains the default slot.
 * @part detail-icon - The chevron icon for the item. Only applies when `detail="true"`.
 */