When a page needs the same interactive UI in several places, a Web Component can package its markup, behavior, and styling behind a reusable HTML tag. It is a design pattern built from browser standards, not a single Web Components API. A well-defined element works alongside native elements and can also be used inside framework applications. section 7.1 section 9.8
Choose the browser features the component actually needs:
- Custom Elements register a class as a tag. An autonomous element extends HTMLElement and is registered with customElements.define(). Give its tag a descriptive name containing a hyphen. section 7.5 section 7.13
- An optional shadow root contains internal markup and scoped styles. Without one, the component remains in the page DOM and participates in its CSS cascade. section 7.5.1 section 7.13
- A template holds inert markup for cloning into instances. Slots can display consumer-provided content, while parts can expose selected shadow-tree elements for styling. section 7.5 section 7.5.2
A reusable counter
Register <counter-button>, then place the tag wherever a counter is needed. Its connectedCallback creates a button and click listener; each instance keeps its own count. Guard DOM setup against repeated connections: connectedCallback can run again when an element moves in the DOM. Do not rely on the constructor to access child DOM that may not yet exist. section 7.7 section 7.9
Listing 7.2 A CounterButton web component
class CounterButton extends HTMLElement {
#count; #1
constructor() {
super();
this.#count = 0; #2
}
connectedCallback() {
if (this.querySelector('button')) return; #3
const button = document.createElement('button');
button.textContent = 'Clicks: 0';
button.addEventListener('click', () => {
this.#count++; #4
button.textContent = `Clicks: ${this.#count}`;
});
this.appendChild(button);
}
}
customElements.define('counter-button', CounterButton);
The counter listing shows registration, per-instance state, a click handler, and a guard against adding another button on reconnection. section 7.7
Treat the host element’s interface as a contract. Use attributes for simple declarative strings, properties for typed or complex values, methods for actions, and events to report changes. Attribute–property synchronization and DOM updates are the component’s responsibility; Custom Elements do not provide built-in reactivity. CSS custom properties can offer styling controls, and shadow components can expose selected parts without making every internal detail part of the styling contract. section 7.5.1 section 7.13
Use encapsulation where it solves a real problem, rather than attaching a shadow root automatically. Rendering with DOM methods, innerHTML, or templates has readability, performance, and security implications. Test DOM behavior and events in a real browser when platform features matter. For routed screens, let the router select the element and pass inputs; leave local rendering to the component. section 7.13 section 9.7 section 11.1.6


