Package a repeated UI block as a shadow-encapsulated custom element

Copy-pasted markup again, and a CSS tweak on the page next door breaks it without anyone touching my code.

BeginnerRead 6 minDoing: an hour6 steps

▶ Start

What you'll have at the end

A custom element whose shadow root keeps its markup and styles unaffected by the surrounding page

Before you start

You need

A UI block whose markup and CSS you've pasted onto more than one page, and a basic grip on JavaScript classes. No build step or bundler required.

Not covered

Letting the surrounding page set this block's own brand colors, or opening one internal element up for the parent to reshape directly. This only builds the sealed box; theming and restyling it from outside are separate jobs.

Leans on

Give the block a real home

Turn the pasted block into one class
Attach an open shadow root first

Fill it in and register it safely

Fill the shadow tree with markup and CSS
Register the tag without crashing twice

Prove it, then replace every paste

Prove the page's rules can't reach in
Swap every pasted copy for the tag

Where to go next

Let outside CSS theme a shadow-DOM component through custom properties

for letting the page hand this block its own brand colors and spacing from outside, once the sealed box itself is done

Expose one internal shadow-DOM element for the parent to restyle with ::part

for opening up one internal element, like the avatar's border, for the parent page to reshape directly

Checked 25 Aug 2026

Part of the Web Components cookbook