Thiago's Blog

Let’s start with the obvious question:

Why use Web Components instead of React?

To be honest, React might still be a better choice for your needs. However, if you’re here, you’re likely curious about experimenting with Web Components, just like I was.

In this post, we’ll aim to replicate some core React-like functionality using Web Components. Our goal is to abstract the conventional Web Components boilerplate into a single, reusable class. By the end of this experiment, we’ll be able to:

Apply styles scoped to individual components
Pass data (props) to a component
Maintain local state within a Web Component
Dynamically update the state and re-render

To demonstrate, we’ll build a blog post. Users will provide the blog title and post body as props, while the component itself will handle rendering the appropriate structure, styling it, and maintaining a "likes counter" in its local state.

The final interface should look like this:

// Component Definition
class BlogPost extends WebComponent {

  // Initial state values
  init() {
    return {
      "<state>" : "<value>"
    };
  }

  // Component styles
  styles() {
    return /* CSS */ `
      .<classname> {
        /* .. */
      }
    `;
  }

  // State update logic
  listeners() {
    // ...
  }

  // Component structure
  html() {
    return /* HTML */ `
      <!-- ... -->
    `.
  }
}

customElements.define("blog-post", BlogPost);

// Usage
<blog-post>
  <h2 slot="post-title">#1 Blog Post</h2>
  <p slot="post-body">
    Lorem ipsum dolor sit amet consectetur,
    adipisicing elit.
  </p>
</blog-post>

This guide assumes you’re already familiar with the basics of the Web Components API. If you are new to it or need a refresher, you can explore the official documentation on MDN: Web Components @ MDN

Declaring Components

Let’s begin by looking at the common boilerplate code needed to create a Web Component, and then expand from that.

// Web Component
class BlogPost extends HTMLElement {
  constructor() {
    super();

    const htmlString = /* HTML */ `
      <div>"I'm a blog post"</div>
    `;

    // Creates a Shadow DOM and attaches elements
    const shadow = this.attachShadow({ mode: "open" });
    shadow.innerHTML = htmlString;
  }
}

customElements.define("blog-post", BlogPost);

// Usage
<blog-post></blog-post>

// React counterpart
function BlogPost() {
  return <div>I'm a blog post</div>;
}

export { BlogPost };

// Usage
<BlogPost></BlogPost>

As you can see, that's a fair amount of code for a simple component definition. While this approach is functional, writing it repeatedly is unlikely to be enjoyable for any modern developer. In the following sections, we’ll tackle this issue and simplify it.

Styling

One way to create styles local to the Web Component (similar to CSS modules) is to use a <template> element. A <style> located inside a <template> will only apply the CSS rules to elements within it.

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

    // Bundle styles and html
    const templateString = /* HTML */ `
      <template>
        <style> div { font-weight: 700; } </style>
        <div>"I'm a blog post"</div>
      </template>
    `;

    // Parses the template
    const template = new DOMParser()
      .parseFromString(templateString, "text/html")
      .querySelector("template").content;

    // Attaches a copy of the parsed template
    const shadow = this.attachShadow({ mode: "open" });
    this.shadow.appendChild(template.cloneNode(true));
  }
}

customElements.define("blog-post", BlogPost);

// React counterpart
function BlogPost() {
  return (
    <div style={{ fontWeight: 700 }}>
      I'm a blog post
    </div>
  );
}

export { BlogPost };

We can now simplify this by creating a reusable WebComponent base class that can be extended through a simpler interface:

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

    const templateString = /* HTML */ `
      <template>
        <style>${this.styles()}</style>
        ${this.html()}
      </template>
    `;

    const template = new DOMParser()
      .parseFromString(templateString, "text/html")
      .querySelector("template").content;

    const shadow = this.attachShadow({ mode: "open" });
    shadow.appendChild(template.cloneNode(true));
  }
}

class BlogPost extends WebComponent {
  constructor() {
    super();
  }

  styles() {
    return /* CSS */ `div { font-weight: 700; }`;
  }

  html() {
    return /* HTML */ `<div>"I'm a blog post"</div>`;
  }
}

customElements.define("blog-post", BlogPost);

Further components can be created by extending the WebComponent class and defining the styles() and html() methods.

Althoug this is not as neat as JSX, you can still get syntax highlighting for the strings returned by styles() and html() by installing the VSCode extension Inline HTML. This is enabled by the /* HTML */ and /* CSS */ comments. Formatting with Prettier also works.

Passing Props

To pass props to a Web Component, all you need is a <slot> element with the correct name.

class BlogPost extends WebComponent {
  //...
  html() {
    return /* HTML */ `
      <div>
        <slot name="post-title">Fallback text.</slot>
      </div>
    `;
  }
}

customElements.define("blog-post", BlogPost);

// Usage
<blog-post>
  <p slot="post-title">The post text</p>
</blog-post>

That way, the contents of the <p> element with the attribute slot="post-title" will be passed to the <slot> element named post-title. Notice that we didn't have to modify the WebComponent base class, as slots provides us the ability to receive props natively.

Keeping Local State

In a Web Component, the component itself is a class, and each instance has its own state. This means that declaring an instance property (e.g., this.state) will create state local to that component by design.

However, we still need to:

Be able to provide initial state values
Be able to update the state
Ensure that when the state changes, the DOM re-renders.

To achieve this, we need to modify our WebComponent base class. First, we’ll move the rendering logic from the constructor to a render method. This will allow us (further down) to easily trigger a re-render whenever the state is updated.

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

    // Creates the Shadow DOM
    this.shadow = this.attachShadow({ mode: "open" });

    // Triggers the first render
    this.render();
  }

  render() {
    // Bundle styles and html
    const templateString = /* HTML */ `
      <template>
        <style>${this.styles()}</style>
        ${this.html()}
      </template>
    `;

    // Parses the template
    const template = new DOMParser()
      .parseFromString(templateString, "text/html")
      .querySelector("template").content;

    // Clears the Shadow DOM
    this.shadow.innerHTML = "";

    // Attaches a copy of the template to the now empty Shadow DOM
    this.shadow.appendChild(template.cloneNode(true));
  }
}

Now, we need to store the state and monitor for changes. One way to do this is by using a Proxy object, which can intercept and react to changes in the state.

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

    // Re-renders the DOM when state is set to a new value
    this._state = new Proxy(this.init(), {
      set: (target, property, value) => {
        if (!Object.is(target[property], value)) {
          target[property] = value;
          this.render();
        }
        return true;
      },
    });

    // Creates the Shadow DOM
    this.shadow = this.attachShadow({ mode: "open" });

    // Triggers the first render
    this.render();
  }

  set state(obj) {
    for (const key in obj) {
      this._state[key] = obj[key];
    }
  }

  get state() {
    return this._state;
  }

 // ...
}

this._state is an instance property that holds an object. The initial value of this object is provided by this.init(), which should be implemented by the BlogPost component. The Proxy ensures that every change in state triggers a re-render with this.render().

Additionally, note that we use a setter — set state() — to handle updates. Directly assigning this._state = { ... } would overwrite the proxy and break the reactivity.

Common ways to trigger state changes in the UI include button clicks and input changes via events. To make event handling easier, we can create a friendlier interface to addEventListener for registering events in the child class.

class WebComponent extends HTMLElement {
  //..

  render() {
    //..

    // Attaches a copy of the template to the now empty Shadow DOM
    this.shadow.appendChild(template.cloneNode(true));

    // Attaches listeners
    this.listeners();
  }

  handle(id, event, handler) {
    this.shadow.getElementById(id).addEventListener(event, handler);
  }
}

To ensure listeners are registered at the correct time, all event listeners should be added using this.handle(), inside the child component's listeners() method. Here’s an example:

// Web Component
class BlogPost extends WebComponent {
  constructor() {
    super();
  }

  init() {
    return {
      likes: 0,
    };
  }

  listeners() {
    this.handle("btn-add-like", "click", () => {
      this.state.likes = this.state.likes + 1;
    });
  }

  styles() {
    return /* CSS */ `
      .post-title {
        color: red;
      }
      .post-body {
        color: blue;
      }
    `;
  }

  html() {
    return /* HTML */ `
      <article>
        <div class="post-title">
          <slot name="post-title">[[Post Title]]</slot>
        </div>
        <div class="post-body">
          <slot name="post-body">[[Post Body]]</slot>
          <p>Likes: ${this.state.likes}</p>
          <button id="btn-add-like">Add +1 Like</button>
        </div>
      </article>
    `;
  }
}

customElements.define("blog-post", BlogPost);

// Usage
<blog-post>
  <h2 slot="post-title">#1 Blog Post</h2>
  <p slot="post-body">
    Lorem ipsum dolor sit amet consectetur,
    adipisicing elit.
  </p>
</blog-post>

<blog-post>
  <h2 slot="post-title">#2 Blog Post</h2>
  <p slot="post-body">
    Deleniti assumenda architecto aliquid
    voluptas eum quam earum quae dolore.
  </p>
</blog-post>

That's it! While this still needs optimization for production, we’ve successfully implemented core React functionality using Web Components.

You can find the full WebComponent class code in the CodePen below.