Common Web Components Mistakes

Web Components Common Mistakes Overview

Web Components are powerful, but small mistakes in naming, lifecycle callbacks, Shadow DOM, slots, styling, events, and accessibility can make components hard to reuse and maintain.

Understanding common mistakes helps you build stable, accessible, framework-independent components that work well across applications and teams.

Common Mistake Example

class BadButton extends HTMLElement {
  connectedCallback() {
    this.innerHTML = `
      <button>${this.getAttribute("label")}</button>
    `;

    window.addEventListener("resize", function() {
      console.log("resize");
    });
  }
}

customElements.define("badbutton", BadButton);

This example has multiple problems: the element name has no hyphen, untrusted attribute content is inserted with innerHTML, and the resize listener is never cleaned up.

50 Web Components Common Mistakes with Fixes

Most Important Mistakes to Avoid

• Using custom element names without a hyphen.
• Defining the same custom element multiple times.
• Forgetting lifecycle cleanup in disconnectedCallback().
• Expecting external CSS to style private Shadow DOM.
• Forgetting bubbles: true and composed: true for public events.
• Using unsafe innerHTML with user-provided content.
• Ignoring accessibility, keyboard support, and focus management.
• Not documenting attributes, properties, events, slots, parts, and CSS variables.

Key Takeaways

• Web Components need stable names, APIs, and lifecycle management.
• Use Shadow DOM only when encapsulation is useful.
• Use CSS Custom Properties and CSS Parts for safe styling hooks.
• Use custom events for clean communication with parent code.
• Clean up listeners, observers, timers, and intervals.
• Accessibility, testing, documentation, and framework compatibility are essential.