Web Components Best Practices

Web Components Best Practices Overview

Web Components best practices help developers build reusable, framework-independent, accessible, secure, and maintainable UI components using browser-native APIs.

Modern Web Components best practices include using clear custom element names, stable public APIs, Shadow DOM only when needed, lifecycle cleanup, CSS Custom Properties, CSS Parts, custom events, accessibility support, and strong documentation.

Web Components Best Practices Example

class AppButton extends HTMLElement {
  constructor() {
    super();

    this.attachShadow({ mode: "open" });

    this.handleClick = this.handleClick.bind(this);
  }

  connectedCallback() {
    this.render();

    this.shadowRoot
      .querySelector("button")
      .addEventListener("click", this.handleClick);
  }

  disconnectedCallback() {
    this.shadowRoot
      .querySelector("button")
      .removeEventListener("click", this.handleClick);
  }

  handleClick() {
    this.dispatchEvent(new CustomEvent("app-click", {
      detail: { clicked: true },
      bubbles: true,
      composed: true
    }));
  }

  render() {
    this.shadowRoot.innerHTML = `
      <style>
        button {
          background: var(--app-button-bg, #0d6efd);
          color: var(--app-button-color, white);
          border: none;
          border-radius: var(--app-button-radius, 0.5rem);
          padding: 0.5rem 1rem;
        }
      </style>

      <button type="button" part="button">
        <slot>Button</slot>
      </button>
    `;
  }
}

if (!customElements.get("app-button")) {
  customElements.define("app-button", AppButton);
}

This example uses a clear element name, Shadow DOM, CSS Custom Properties, CSS Parts, slots, custom events, lifecycle callbacks, and duplicate definition protection.

50 Web Components Best Practices with Examples

The following table lists important Web Components best practices for beginners, frontend developers, design system developers, and frontend architects.

Common Mistakes to Avoid

• Defining a custom element name without a hyphen.
• Calling customElements.define() multiple times for the same name.
• Doing too much DOM work inside the constructor.
• Forgetting to clean up event listeners, observers, timers, or intervals.
• Using Shadow DOM when simple light DOM would be enough.
• Using closed Shadow DOM when debugging and testing are important.
• Expecting normal external CSS selectors to style private Shadow DOM elements.
• Forgetting composed: true for public events from Shadow DOM.

Key Takeaways

• Web Components best practices improve reuse, stability, and maintainability.
• Use clear custom element names and stable public APIs.
• Use Shadow DOM, slots, CSS Custom Properties, and CSS Parts intentionally.
• Use custom events for clean communication with parent components.
• Clean up listeners, observers, timers, and intervals.
• Prioritize accessibility, documentation, testing, and framework interoperability.