Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 37 ยท Getting Started

Web Components and Shadow DOM in Ionic

Understand why Ionic components are custom elements, how shadow DOM, slots, properties and events work, and how this affects styling and testing.

Every ion-* tag you write is a custom element, built with Stencil, Ionic's compiler for Web Components. Understanding what that means saves hours of confusion later: why a CSS rule does not reach inside a button, why some events are named ionChange, and why you query properties rather than attributes. This lesson covers the four browser standards underneath Ionic.

The four standards

  1. Custom elements let you define a new tag such as <ion-button> with its own behaviour.
  2. Shadow DOM gives the element a private internal tree whose styles do not leak out.
  3. Slots let you place your own content into designated holes of that private tree.
  4. Events and properties are the public API of the element.
flowchart TD
  A["ion-button (host element)"] --> B["#shadow-root"]
  B --> C["button.native"]
  C --> D["span.button-inner"]
  D --> E["slot (your text goes here)"]

Inside the host, Ionic renders a real button and a slot that receives your content.

Custom elements

A custom element is registered once with customElements.define. After that the browser upgrades every matching tag. You can see the mechanism with a small stand-in that behaves like a very simplified Ionic component. It uses plain JavaScript; the registry here is a tiny fake so it can run outside a browser.

JS Stand-in: a registry of custom elements

Press Run (or Ctrl + Enter) to see the console output here.

No output.

In real apps you must make sure Ionic's components are registered before they are used. Frameworks do this when you import them; with the CDN script, loading it does it. A tag that was never registered stays an unknown element, and it renders as an empty inline box with no styles.

Shadow DOM and styling

Because each component keeps its internals in shadow DOM, a normal CSS selector cannot style them:

CSS
/* Does NOT work: the inner button is inside the shadow root. */
ion-button button { background: hotpink; }

Ionic gives you three official ways to style across that boundary:

CSS
/* 1. CSS custom properties (variables) are inherited through the shadow boundary */
ion-button {
  --background: hotpink;
  --border-radius: 20px;
  --padding-start: 24px;
}

/* 2. CSS shadow parts expose named inner elements */
ion-button::part(native) {
  letter-spacing: 0.05em;
}

/* 3. The host element itself can be styled with normal CSS */
ion-button {
  margin: 8px;
  width: 100%;
}

The documented variables and parts of each component are listed in its API page under "CSS Custom Properties" and "CSS Shadow Parts". Prefer variables; use ::part for things variables cannot reach.

Slots

A slot is a named hole in a component's shadow tree. Content you write between the tags is projected into the matching slot:

HTML
<ion-item>
  <ion-icon name="mail" slot="start"></ion-icon>
  <ion-label>Inbox</ion-label>
  <ion-badge slot="end">4</ion-badge>
</ion-item>

Here slot="start" puts the icon before the label and slot="end" puts the badge after it. Children with no slot attribute go to the default slot. Slot names are case-sensitive and documented per component.

The following stand-in projects children into named slots exactly like the browser does, so you can see the rules: unnamed children use the default slot, and unknown names fall back to the default.

JS Stand-in: slot projection

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Properties, attributes and events

HTML attributes are always strings. Ionic components also accept rich values through properties, such as an array of options or a function. In frameworks you rarely notice because bindings take care of it. In plain HTML you must set properties from script:

HTML
<ion-select id="fruit" label="Fruit"></ion-select>
<script>
  const sel = document.querySelector('#fruit');
  sel.interfaceOptions = { header: 'Pick a fruit' };
  sel.addEventListener('ionChange', (e) => console.log(e.detail.value));
</script>

Events carry data in event.detail. Most Ionic events are prefixed with ion and do not collide with native events. Some are cancelable, and a few bubble. Check the Events table on the component's API page.

Methods

Components also expose methods that you call on the element: modal.present(), content.scrollToBottom(), searchbar.setFocus(). Frameworks give you a typed reference (@ViewChild in Angular, useRef in React, a template ref in Vue). In plain HTML you call them directly, and they usually return a promise because they animate.

What this means for testing

Shadow DOM hides internals from simple selectors. Test libraries query by role or text, or reach into shadowRoot, or use Ionic's test helpers. In end-to-end tests, locate elements by the host tag and its test id (data-testid) and interact through the public API. You will do this in testing and performance chapters.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does ion-button button { ... } not style the inner button?

    Shadow DOM encapsulates the internals, so outside selectors cannot reach them. Use CSS variables or ::part.
  2. 2. Which approach does Ionic recommend first for customising a component?

    Custom properties are inherited into the shadow tree and are the stable styling API.
  3. 3. Where does a child with slot="end" appear in an ion-item?

    Named slots project children into the matching region defined by the component.
  4. 4. Where is the data for an ionChange event?

    Ionic custom events place their payload in event.detail.

Summary

  • Ionic components are custom elements built with Stencil.
  • Shadow DOM hides internals; style through CSS variables, ::part and the host element.
  • Slots (start, end, default) place your content into a component.
  • Rich data goes through properties; events are named ion* and carry event.detail.
  • Components expose async methods such as present().

Next: Buttons, Cards and Icons