Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 39 ยท Getting Started

How Custom Elements, Shadow DOM and Templates Fit Together

See how Custom Elements, Shadow DOM and HTML templates cooperate inside one component, and try each technology on its own to understand what it contributes.

The three technologies behind Web Components were designed to be independent. That is a strength: you can adopt one without the others, and you can understand each by testing it alone. In this lesson you pull them apart, use each in isolation, and then see exactly where each one plugs into a finished component.

Custom Elements alone

A custom element with no shadow root and no template is still a custom element. It adds behavior to a tag, and its children live in the normal page tree where page CSS applies.

Custom element without Shadow DOM

Because there is no shadow root, the page rule time-ago { color: ... } styles it. Light-DOM components are ideal when you want the page's CSS to control the look, such as a content tag that inherits site typography.

Shadow DOM alone

Shadow DOM does not need a custom element. You can attach a shadow root to a handful of built-in elements, such as <div>, <section>, <article>, <p>, <span> and the heading elements.

Shadow DOM on a plain div

The page counts one <p>, because document.querySelectorAll does not look inside the shadow tree, and the red rule does not affect the green paragraph. A plain <div> has become an isolated mini-document.

Templates alone

<template> has nothing to do with custom elements. It is simply a way to hold markup that the browser parses but does not render, run or load.

Cloning a template

The <li> in the template is never displayed by itself. Scripts and images inside a template do not run or load until you clone and insert them. A template is a stencil.

Putting them together

A finished component assigns each technology one job.

flowchart TB
  CE["Custom Element: the tag, the class, the lifecycle"]
  SD["Shadow DOM: the private tree and scoped CSS"]
  TP["Template: the markup stencil"]
  SL["Slot: where the user's content appears"]
  CE -->|attachShadow| SD
  TP -->|cloneNode| SD
  SL -->|inside the template| TP

The custom element is the owner. It creates the shadow root, fills it from a template, and exposes slots for the page's content.

The combined version of the earlier row example looks like this: one tag, one stencil, one private tree.

All three together

The class (custom element) builds the shadow root, the template supplies the markup, <slot> receives the text you wrote between the tags, and ::slotted(strong) styles that slotted content from inside.

Which combination should you choose?

Need Use
A tag whose look is controlled by the site CSS Custom element only (light DOM)
Isolation for an embedded widget Custom element + Shadow DOM
Repeated rows or items created from script Template only
A reusable design-system component All three

A useful rule: start with a light-DOM custom element for simple enhancement and add Shadow DOM when you notice style collisions or want a hard boundary.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which technology can be used without the other two?

    Custom elements, shadow roots (on supported built-in elements) and templates are separate APIs that can be used on their own.
  2. 2. A script inside a template element ...

    Template content is inert. Scripts, images and other resources are not activated until the cloned content is inserted.
  3. 3. Why does document.querySelectorAll('p') not find paragraphs inside a shadow root?

    Document-level queries stop at the shadow boundary, which is what makes the internals private.
  4. 4. Which technology gives a component its own lifecycle callbacks?

    Lifecycle callbacks such as connectedCallback belong to the custom element class.

Summary

  • Custom Elements provide the tag, class and lifecycle.
  • Shadow DOM provides a private tree with scoped CSS and works even on a plain <div>.
  • Templates provide inert, cloneable markup; slots let users fill parts of it.
  • Light-DOM components let page CSS control the look; shadow components isolate it.
  • A full component combines all three, each with one clear job.

Next: Web Components and Frameworks