The 2025 Guide: 7 Steps to Master Vanilla Web Components

class GreetingMessage extends HTMLElement {
  constructor() {
    super();
    // Attach a shadow root to the element.
    // 'open' mode means you can access the shadow DOM from JavaScript.
    this.attachShadow({ mode: 'open' });
  }

  connectedCallback() {
    // Now, we append content to the shadowRoot instead of using innerHTML
    this.shadowRoot.innerHTML = `
      <style>
        p {
          color: green;
          font-family: sans-serif;
        }
      </style>
      <p>Hello, Encapsulated World!</p>
    `;
  }
}

customElements.define('greeting-message-shadow', GreetingMessage);

Now, the p style is scoped only to this component. A global p { color: red; } style on your page will not affect “Hello, Encapsulated World!”. This is true encapsulation.

Step 4: Make it Reusable with Templates and Slots

Hardcoding HTML inside a JavaScript string isn’t ideal. For more complex components, we use the <template> and <slot> elements. A <template> is an inert piece of DOM, parsed but not rendered, making it highly efficient to clone.

A <slot> is a placeholder inside your component that you can fill with your own markup from the outside. This is called “content projection.”

Let's create a more flexible profile card:

// In your HTML, define the template
<template id="profile-card-template">
  <style> .card { border: 1px solid #ccc; padding: 1rem; } </style>
  <div class="card">
    <h3><slot name="username">Default User</slot></h3>
    <div class="details">
      <slot>Default bio content goes here.</slot>
    </div>
  </div>
</template>

// In your JavaScript
class ProfileCard extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    const template = document.getElementById('profile-card-template');
    const content = template.content.cloneNode(true);
    this.shadowRoot.appendChild(content);
  }
}
customElements.define('profile-card', ProfileCard);

// How to use it in HTML:
<profile-card>
  <span slot="username">Elena Petrova</span>
  <p>Loves building things for the web.</p>
</profile-card>

Notice how the <span> with slot="username" is projected into the <slot name="username"> placeholder. The <p> tag without a name goes into the default (unnamed) <slot>.

Step 5: Handle Attributes and Properties

Components need to accept data. The two primary ways are via HTML attributes (e.g., <my-el attribute="value">) and JavaScript properties (e.g., myEl.property = 'value').

A best practice is to keep them in sync. Web components provide a lifecycle callback to react to attribute changes.

Let’s create a user avatar component that takes a src attribute:

class UserAvatar extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this.shadowRoot.innerHTML = `<img alt="User Avatar">`;
    this._imgElement = this.shadowRoot.querySelector('img');
  }

  // 1. Specify which attributes to observe for changes
  static get observedAttributes() {
    return ['src'];
  }

  // 2. React to changes in those attributes
  attributeChangedCallback(name, oldValue, newValue) {
    if (name === 'src' && oldValue !== newValue) {
      this._imgElement.src = newValue;
    }
  }

  // 3. (Optional but good practice) Create a JS property getter/setter
  get src() {
    return this.getAttribute('src');
  }

  set src(value) {
    this.setAttribute('src', value);
  }
}

customElements.define('user-avatar', UserAvatar);

// Usage: <user-avatar src="/path/to/image.jpg"></user-avatar>

Now, whenever the `src` attribute changes on the element, `attributeChangedCallback` fires and updates the internal `` tag. The getter/setter pair allows you to interact with it programmatically (e.g., `document.querySelector('user-avatar').src = 'new.jpg';`).

Step 6: Manage State and Events

Components aren’t just for display; they need to be interactive. This involves managing internal state and communicating changes to the outside world. The standard way to communicate *out* of a component is by dispatching custom events.

Let’s build a simple counter button:

class CounterButton extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    // Internal state
    this._count = 0;

    this.shadowRoot.innerHTML = `
      <button>Times Clicked: 0</button>
    `;

    this._button = this.shadowRoot.querySelector('button');
    this._button.addEventListener('click', this._increment.bind(this));
  }

  _increment() {
    this._count++;
    this._render();

    // Dispatch a custom event to notify the outside world
    this.dispatchEvent(new CustomEvent('countChanged', {
      detail: { count: this._count } // Pass data with the event
    }));
  }

  _render() {
    this._button.textContent = `Times Clicked: ${this._count}`;
  }
}

customElements.define('counter-button', CounterButton);

// In your main script, you can listen for this event
const myCounter = document.querySelector('counter-button');
myCounter.addEventListener('countChanged', (event) => {
  console.log(`The count is now: ${event.detail.count}`);
});

This pattern is powerful. The component manages its own state and logic, and provides a clean event-based API for other parts of your application to hook into, without needing to know about its internal implementation.

Step 7: Style Your Component Like a Pro

Styling is often a point of confusion. Because of the Shadow DOM, external styles don’t get in, but how do you let users customize your component? You have a few professional-grade tools at your disposal.

The :host Selector

Inside your Shadow DOM's <style> tag, :host allows you to style the component element itself (the “host” element).

:host { 
  display: inline-block; /* By default, custom elements are display: inline */
  border: 1px solid gray;
}

:host([disabled]) { /* Style the host when it has a 'disabled' attribute */
  opacity: 0.5;
  pointer-events: none;
}

CSS Custom Properties (Variables)

This is the primary way to create a “theming API” for your component. Define default values for custom properties inside your component, which users can then override from the outside.

/* Inside the component's <style> tag */
:host {
  --button-background: dodgerblue;
  --button-color: white;
}
button {
  background-color: var(--button-background);
  color: var(--button-color);
}

/* In your global stylesheet, a user can override them */
counter-button {
  --button-background: darkred;
}

The ::part() Pseudo-element

Sometimes, you need to give users more granular control. By adding a part attribute to an element inside your Shadow DOM, you can make it targetable from the outside using the ::part() pseudo-element.

// Inside the component's template
<button part="counter-btn">Click Me</button>

// In your global stylesheet
counter-button::part(counter-btn) {
  border-radius: 8px;
  box-shadow: 2px 2px 5px rgba(0,0,0,0.2);
}

Using these three techniques—:host, custom properties, and ::part()—gives you a robust and flexible styling system that respects encapsulation while allowing for necessary customization.

Conclusion: You're Ready to Build!

And there you have it! We've journeyed through the seven essential steps to mastering vanilla Web Components. From understanding the core concepts and defining your first element, to managing state, events, and advanced styling, you now have the foundational knowledge to build your own robust, reusable, and framework-agnostic UI components.

The beauty of Web Components is their longevity. They aren’t a fleeting trend; they are a web standard. The components you build today will work in browsers for years to come. So go ahead, start small with a custom button or a profile card, and see how liberating it can be to build directly on the platform.