Web Components API Reference

Web Components APIs at a Glance

Web Components are built on browser-native APIs. This reference summarizes the most important interfaces and methods you use when creating, styling, composing, and communicating with custom elements in production projects.

Custom Elements API

class AppBadge extends HTMLElement {
  static get observedAttributes() {
    return ["variant"];
  }

  constructor() {
    super();
  }

  connectedCallback() {
    this.render();
  }

  attributeChangedCallback(name, oldValue, newValue) {
    if (oldValue !== newValue) this.render();
  }
}

customElements.define("app-badge", AppBadge);

Attributes and Properties API

class ToggleSwitch extends HTMLElement {
  static get observedAttributes() {
    return ["checked"];
  }

  get checked() {
    return this.hasAttribute("checked");
  }

  set checked(value) {
    this.toggleAttribute("checked", Boolean(value));
  }

  attributeChangedCallback(name) {
    if (name === "checked") {
      this.dispatchEvent(
        new Event("change", { bubbles: true })
      );
    }
  }
}

Use attributes for declarative HTML configuration and properties for rich JavaScript values such as objects, arrays, and functions.

Shadow DOM API

class ProfileCard extends HTMLElement {
  constructor() {
    super();
    this.shadow =
      this.attachShadow({ mode: "open" });

    this.shadow.innerHTML = `
      <style>
        :host { display: block; }
        .card { padding: 1rem; border: 1px solid #ccc; }
      </style>
      <article class="card" part="card">
        <slot name="title"></slot>
        <slot></slot>
      </article>
    `;
  }
}

HTML Template API

<template id="user-row-template">
  <article class="row">
    <strong><slot name="name"></slot></strong>
    <span><slot name="role"></slot></span>
  </article>
</template>

class UserRow extends HTMLElement {
  connectedCallback() {
    const template =
      document.getElementById("user-row-template");
    const content =
      template.content.cloneNode(true);

    this.appendChild(content);
  }
}

Slots API

<info-card>
  <h2 slot="title">Billing</h2>
  <p>Your plan renews tomorrow.</p>
  <button slot="footer">Manage</button>
</info-card>

class InfoCard extends HTMLElement {
  connectedCallback() {
    this.innerHTML = `
      <section>
        <header><slot name="title"></slot></header>
        <div><slot></slot></div>
        <footer><slot name="footer"></slot></footer>
      </section>
    `;

    this.querySelector("slot").addEventListener(
      "slotchange",
      () => this.handleSlotChange()
    );
  }
}

Custom Events API

this.dispatchEvent(
  new CustomEvent("item-selected", {
    detail: {
      id: this.itemId,
      label: this.label
    },
    bubbles: true,
    composed: true,
    cancelable: true
  })
);

ElementInternals API

class AppTextInput extends HTMLElement {
  static formAssociated = true;

  constructor() {
    super();
    this.internals = this.attachInternals();
  }

  connectedCallback() {
    this.innerHTML = `<input type="text" />`;
    this.input = this.querySelector("input");
    this.input.addEventListener("input", () => {
      this.internals.setFormValue(this.input.value);
    });
  }
}

Styling APIs

app-button {
  --btn-bg: #2563eb;
  --btn-color: white;
}

app-button::part(button) {
  border-radius: 0.5rem;
}

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  button { background: var(--btn-bg, #111); }
`);

this.shadowRoot.adoptedStyleSheets = [sheet];

Declarative Shadow DOM

<profile-card>
  <template shadowrootmode="open">
    <style>
      :host { display: block; }
    </style>
    <article><slot></slot></article>
  </template>
  <p>Alex Chen</p>
</profile-card>

Declarative Shadow DOM lets you define a shadow tree directly in HTML. This is useful for server-side rendering and progressive enhancement without waiting for JavaScript to attach a shadow root.

Quick Reference by Task

When to Use Each API

• Use customElements.define() for every reusable custom tag.
• Use Shadow DOM when internal structure and CSS should stay private.
• Use templates when markup should be cloned instead of rebuilt as strings.
• Use slots when consumers need flexible composition.
• Use custom events when parent apps need output from a component.
• Use ElementInternals for custom form controls and validation.
• Use CSS parts and custom properties when theming must stay controlled.

API Usage Best Practices

• Keep the public API small: attributes, properties, events, and slots.
• Document every observed attribute and emitted event.
• Prefer open shadow roots unless strong encapsulation is required.
• Use composed: true only when parent apps must hear the event.
• Sync attributes and properties predictably for framework consumers.
• Clean up listeners and timers in disconnectedCallback().
• Expose styling hooks intentionally instead of leaking all internals.

Common API Mistakes

• Calling attachShadow() more than once on the same element.
• Forgetting to declare observedAttributes before watching changes.
• Using attributes for object values instead of properties.
• Emitting events without documenting names and detail shape.
• Overusing closed Shadow DOM and breaking testing or theming.
• Not using composed: true for events that must leave Shadow DOM.
• Exposing too many internal parts and defeating encapsulation.

Key Takeaways

• Web Components are powered by a small set of browser-native APIs.
• Custom Elements handle behavior, Shadow DOM handles encapsulation.
• Templates and slots enable reusable and composable markup.
• Custom events and ElementInternals extend the public contract.
• This reference is the foundation for building production-ready components.