Forem: Burton Smith

How Declarative Custom Elements (DCE) Could Improve Web Components

Burton Smith — Tue, 24 Mar 2026 12:06:44 +0000

In a previous article, I wrote about the state of SSR for Web Components. Since then, I have received many questions about when we will see Declarative Custom Elements (DCEs). Teams are looking for ways to eliminate JavaScript requirements for presentational components, address FOUC, and simplify SSR solutions.

Current Challenges with Web Components

As the adoption of web components continues to grow, teams encounter challenges with their client-side-only nature. Components require JavaScript for initial rendering, which can lead to Flash of Unstyled Content (FOUC). Server-side rendering implementations require framework-specific integrations and are often complex. Even purely presentational components need JavaScript to bootstrap their markup and styles.

Requires JavaScript

Even for purely presentational components that consist only of markup and CSS, JavaScript is required to bootstrap the component definition.

Flash of Unstyled Content

A frequently cited issue with web components is FOUC, which occurs during page load.

This issue is particularly problematic for teams using content management systems that lazy-load components for performance optimization. The delay between initial page load and component rendering creates a suboptimal user experience.

For information on how to reduce FOUC on your pages, check out my article on the topic.

Server-Side Rendering (SSR)

SSR support for web components requires framework-specific implementations, often with specific configuration requirements and restrictions on APIs that can be used in component authoring.

Declarative Shadow DOM

Recognizing these pain points, the web platform introduced Declarative Shadow DOM as a solution. While DSD made progress, it brought its own set of trade-offs.

Scalability

DSD templates cannot be reused - they must be repeated for each component instance on a page. Got 50 buttons? That's 50 complete shadow DOM templates - styles and all. Here's a very simple example of what that looks like:

<my-button>
  <template shadowrootmode="open">
    <style>
      button {
        padding: 0.25rem;
        border: solid 1px black;
      }
    </style>
    <button>
      <slot></slot>
    </button>
  </template>
  My Button 1
</my-button>

<my-button>
  <template shadowrootmode="open">
    <style>
      button {
        padding: 0.25rem;
        border: solid 1px black;
      }
    </style>
    <button>
      <slot></slot>
    </button>
  </template>
  My Button 2
</my-button>
<!-- Repeat for EVERY custom button... -->

You can see the limitation here. Each component instance requires the complete template, resulting in significant duplication of styles and markup across the page. This is the HTML equivalent of repeating a function definition instead of calling a reusable function.

Library Dependency

In order to hydrate web components with a Declarative Shadow DOM, teams depend on library-specific integrations to parse and inject the component's content into the DOM. This often comes with particular configuration requirements and constraints on component authoring patterns.

SSR Complexity

Server-side rendering of client-side code has no standard. Each framework implements its own approach. That means for your web components to be server-rendered in frameworks, you need a special implementation for each of those frameworks.

Enter Declarative Custom Elements

The core concept behind DCEs is simple: define a custom element template once and reuse it throughout the document. This addresses the duplication issues inherent in DSD while maintaining the benefits of declarative markup.

Here's what a simple DCE definition could look like:

<definition name="my-element">
  <template shadowrootmode="closed">
    ...
  </template>
</definition>

NOTE: All DCE examples and APIs in the article are hypothetical and have not been defined yet.

The first phase of this could basically be a reusable Declarative Shadow DOM. The definition is specified once, then the element can be used multiple times throughout the document. No duplication, no JavaScript required for initial rendering, and no FOUC.

A Real Example

Let's look at a more realistic example. Here's a simple badge component with multiple variants and styling.

<definition name="my-badge">
  <template shadowrootmode="open">
    <style>
      :host {
        --badge-fg-color: white;
        --badge-bg-color: blue;
        --badge-border-color: blue;
        padding: 8px;
        border-radius: 4px;
      }

      :host([hollow]) {
        --badge-fg-color: blue;
        --badge-bg-color: transparent;
      }

      :host([variant="danger"]) {
        --badge-bg-color: red;
        --badge-border-color: red;
      }

      :host([variant="warning"]) {
        --badge-fg-color: black;
        --badge-bg-color: yellow;
        --badge-border-color: yellow;
      }

      .base {
        color: var(--badge-fg-color);
        background-color: var(--badge-bg-color);
        border: 1px solid var(--badge-border-color);
      }
    </style>
    <span class="base" part="base">
      <slot></slot>
    </span>
  </template> 
</definition>

Now you can use it anywhere in your markup:

<my-badge>Default</my-badge>
<my-badge hollow>Hollow</my-badge>
<my-badge variant="danger">Danger</my-badge>
<my-badge variant="warning">Warning</my-badge>

Each badge renders immediately with the correct styles. The browser can render <my-badge> elements because the definition is available declaratively in the document.

Benefits of DCEs

No JavaScript Required

Removing the JavaScript requirement for CSS-only components provides significant benefits. Many design system components are purely presentational, like badges and layout components, which don't require interactivity. With DCEs, these components function correctly even when JavaScript is disabled, slow to load, or blocked.

Improved FOUC Experience

DCEs address the Flash of Unstyled Content issue directly. Components render immediately with correct styles because the browser has access to the template definition from the start. This eliminates the delay while JavaScript loads, executes, and defines custom elements.

Simplified Server-Side Rendering

DCEs could greatly simplify and standardize the SSR implementation for a more framework-agnostic approach to pre-rendering components. Instead of relying on framework-specific integrations with their own quirks and restrictions, you could pre-render DCEs in a standardized way that works anywhere.

Progressive Enhancement

DCEs could support progressive enhancement naturally. If interactivity is needed, custom elements can be upgraded by defining them with JavaScript. The DCE provides the initial render, and JavaScript adds behavior when available - combining the benefits of both approaches. This hybrid approach means your design system components work immediately for all users, while JavaScript-enhanced features activate seamlessly for those with JS enabled.

How to Use Them

How can we translate our existing components into DCEs and make sure they end up on the page when we need them?

I think there are many ways to solve this problem. Much of this will depend on your development environment, tooling, and framework preferences.

I made a simple proof-of-concept that parses the Custom Elements Manifest and generates them in various formats, including framework wrappers, so they can be provided by libraries and easily imported into an application.

NOTE: Again, all DCE examples and APIs in this article are hypothetical and have not been defined yet.

Real-World Performance Analysis

I conducted performance experiments on a site using Shoelace, a popular web component library, and the DCE Generator mentioned above, to evaluate the practical impact of DCEs:

Test setup: A page with 1,362 custom elements - 943 of them Shoelace components, using 22 different components from the library.

DSD approach: Generating Declarative Shadow DOM for each component instance added about 1.9MB of markup and CSS

DCE approach: Loading all 58 Shoelace DCE definitions added about 150KB of markup and CSS

This represents a significant difference: 150KB versus 1.9MB - approximately 12x smaller. This also does not include the contents of the other 419 components on the page. Additionally, the DCE payload size remains constant regardless of component instance count, while DSD increases with each component instance.

This page has since been refactored to be more lightweight (thankfully), but pages like this are not outside the realm of possibility for large, complex applications.

The good news is that because of the repetition of the templates, the DSD example was efficiently gzipped and was not much larger than the DCE version for file transfer.

These findings suggest that DCEs offer predictable performance characteristics and scalable markup strategies, especially for large applications with many repeated components.

Implementation Challenges and Open Questions

While the proposal offers clear benefits, there are some exciting design questions to explore as the specification develops.

Scope Management

Discussions about DCEs tend to expand into related APIs and features. Maintaining focus on a minimal, achievable initial proposal while acknowledging future extensibility is an ongoing challenge.

Future phases of this API should include things like attribute mapping and integration with DOM parts, but the initial proposal of reusable shadow DOMs would provide huge benefits in performance and user experience.

Browser Implementation

Achieving consensus and implementation across all major browsers presents coordination challenges. However, DCEs build on existing web platform primitives like templates and custom elements, which may facilitate implementation.

FAQs

Can I use DCEs today?

No. DCEs are a proposal, and all APIs shown in this article are hypothetical. No browser has implemented them yet, and the specification is still being defined.

However, the proof-of-concept DCE Generator package on npm lets you experiment with the concept by parsing your Custom Elements Manifest and generating definitions in various formats, including framework wrappers.

How are DCEs different from Declarative Shadow DOM?

DSD lets you define shadow DOM declaratively, but requires a full template copy for every single component instance on the page. DCEs build on that foundation by allowing you to define the template once and reuse it across all instances, solving DSD's core scalability and framework integration problems.

What about attributes?

Attributes are a key aspect of custom elements. I have an API proposal for this, but attribute binding would likely be a fast-follow feature since they would depend on a feature like DOM Parts, whose spec is still in development.

Because it depends on a feature that is still in development and not required to address some of these initial issues, it would be a shame not to hold these features hostage waiting for that.

What about conditional rendering?

Some components render different content depending on defined attributes or slotted content (ie - button components that can render a button or an anchor tag). This would add a great deal of flexibility to components, but, like attributes, would likely depend on specs that aren't available yet, like DOM Parts and additional elements or attributes to make it work. This would need to be a feature that comes in a future iteration of the spec.

What about lifecycle hooks?

In their initial form, they probably won't have lifecycle hooks. The core proposal is focused on declarative, presentational rendering - essentially a reusable shadow DOM template that requires no JavaScript. Lifecycle hooks like connectedCallback, disconnectedCallback, and attributeChangedCallback are fundamentally JavaScript APIs and wouldn't fit the no-JS nature of a pure DCE.

If access to those is needed, they can be included in the autonomous custom element defined in JavaScript.

Should these only work with Shadow DOM?

Autonomous custom elements can be rendered without a shadow root, so should DCEs allow rendering into the light DOM, not just the shadow DOM? This could broaden their applicability and simplify integration with existing markup, but it also introduces questions about style encapsulation and component boundaries.

Conclusion

Declarative Custom Elements represent a natural evolution of the web platform's component story. By building on the foundation of Declarative Shadow DOM and addressing its scalability limitations, DCEs promise to make web components more accessible, performant, and developer-friendly.

Declarative Shadow DOM has been a great step in improving the web component ecosystem. Declarative Custom Elements feel like the next evolution of that vision, with exciting capabilities for dynamic templating and data mapping with technologies like DOM Parts to follow.

Reducing FOUC with Web Components

Burton Smith — Sat, 31 Jan 2026 19:11:10 +0000

The Problem

One of the best things about web components is that they are wicked fast, but one of the common complaints I hear is that, because they are a client-side technology, there can be a delay between when the page renders and the components are defined and rendered. This can result in a flash of unstyled content (FOUC) and page content shifts - that jarring moment when your carefully crafted layout suddenly jumps around before your users' eyes. Not exactly the first impression we're going for.

You can see each of these solutions described in this article in action in this demo site.

The Old Solution

Here's the solution that's been making the rounds for ages:

:not(:defined) {
  visibility: hidden;
}

What's happening?

This CSS selector targets any custom element that hasn't been defined yet and visually hides it from view. Once the JavaScript defines the custom element, the browser marks it as :defined, the selector no longer matches, and the component becomes visible.

Pros

Performant and simple: Just drop it in a CSS reset or theme file, and you're done.
Zero setup required: Developers using your components don't need to do anything special - it just works out of the box.

Cons

Layout shifts: Because this only hides the component visually (the element still takes up space in the layout). The element initially renders as an unstyled HTMLUnknownElement, which has no intrinsic size. As components load and apply their styles, it can result in content jumps as the page reflows.
Silent failures: If a component fails to define (network issues, JavaScript errors, etc.), it will never be shown. This might be acceptable in some cases, but it's problematic if you're using custom elements for progressive enhancement or mixing defined and undefined custom elements in your application.
Accessibility issues: Using visibility: hidden; can remove the content from the accessibility tree, which means screen readers and other assistive technologies can't access it. Your content is invisible to both sighted users and accessibility tools, which can affect initial focus.

Solving it with JavaScript

In a previous article I wrote, I show how to use native JavaScript APIs to improve upon the original solution:

<style>
  /* Visually block initial render as components get defined */
  body:not(.wc-loaded) {
    opacity: 0;
  }
</style>
<script type="module">
  (() => {
    // Select all undefined custom elements on the page and wait for them to be loaded.
    // Once they are all loaded, add the `wc-loaded` class to the body to make it visible again.
    Promise.allSettled(
      [...document.querySelectorAll(":not(:defined)")]
        .map((component) => {
          return customElements.whenDefined(component.localName);
        })
    ).then(() => document.body.classList.add("wc-loaded"));

    // Add fallback to add the `wc-loaded` class to the body to make it visible after 200ms. 
    // This prevents the user from being blocked from using your application in case a component fails to load
    // or other undefined elements are being used on the page.
    setTimeout(() => document.body.classList.add("wc-loaded"), 200);
  })();
</script>

What's happening?

This approach waits for all custom elements to be defined before revealing the page. Here's how it works:

Hide the body: We set opacity: 0 on the body until it gets the wc-loaded class. Unlike visibility: hidden, this keeps content in the accessibility tree - screen readers can still access it.
Query for undefined elements: document.querySelectorAll(":not(:defined)") finds all custom elements that haven't been defined yet.
Wait for definition: For each undefined element, we use customElements.whenDefined(), which returns a Promise that resolves when that custom element gets defined.
Wait for all components: Promise.allSettled() waits for all those Promises to complete (whether they succeed or fail), then adds the wc-loaded class to make everything visible.
Fallback timeout: The setTimeout ensures that even if something goes wrong, users aren't staring at a blank page forever. After 200ms, we show the page regardless.

Pros

Accessibility-friendly: By using opacity instead of visibility: hidden, the page content remains available to assistive technologies. Users with screen readers aren't left in the dark.
Graceful degradation: Provides a fallback in case components fail to load or if undefined custom elements are also being used on the page. Your users will see something rather than nothing.
Very performant: Modern browsers handle opacity changes efficiently, and the JavaScript overhead is minimal.
Future-proof: By adding a class instead of directly manipulating styles, you avoid issues where new components added after page load might cause the opacity to flash in and out.

Cons

Setup required: Depending on your architecture, this might need to be included in your base template or injected into every page. It's not quite as "set it and forget it" as a CSS-only solution.
JavaScript dependency: Requires JavaScript to execute on the page before content is visible. If JS is disabled or fails to load, users see nothing (though the timeout helps mitigate this).
Module timing: The script needs to run as a module, which means it's deferred and runs after the DOM is loaded. This can introduce a small delay compared to inline scripts or CSS-only solutions.
Potential failure point: If JavaScript is disabled or fails to load the script, it could prevent the page from loading properly.

Solving it with CSS

What if we could have the best of both worlds - a solution that's easy to set up, lightweight, doesn't require additional JavaScript to run, and provides a fallback if components fail to load? Here's a CSS-only approach:

/* must define property to work properly for all browsers */
@property --wc-loaded {
  syntax: "<number>";
  inherits: true;
  initial-value: 0;
}

body {
  /* start timeout regardless if there are undefined components */
  animation: showBody 0s linear 200ms forwards;

  /* if there are undefined components, hide until defined or 200ms - whichever comes first */
  &:has(:not(:defined)) {
    opacity: var(--wc-loaded, 0);
  }
}

/* update variable to prevent opactity flash for subsequent component loads */
@keyframes showBody {
  to {
    --wc-loaded: 1;
  }
}

What's happening?

@property --wc-loaded - Defines a custom CSS property with an initial value of 0. This is required for proper browser compatibility and serves as a flag to track component loading state.
animation: showBody 0s linear 200ms forwards - Sets up a zero-duration animation with a 200ms delay. This serves two purposes:
- Creates a timeout mechanism that ensures the page displays after 200ms even if components are slow to load
- Updates the --wc-loaded property to 1 after the delay
:not(:defined) - A powerful CSS pseudo-class that selects any custom elements that haven't been registered with the browser yet. This includes all web components that are still loading or haven't been defined.
body:has(:not(:defined)) - Uses the :has() pseudo-class to check if the body contains ANY undefined custom elements. This selector dynamically evaluates as components are defined.
opacity: var(--wc-loaded, 0) - Sets the body opacity to the value of --wc-loaded (defaulting to 0). When undefined components exist:
- Initially: opacity is 0 (page hidden)
- After 200ms: --wc-loaded becomes 1 (page shows)
- After all components load: the :has(:not(:defined)) selector stops matching, removing the opacity override entirely
@keyframes showBody - Defines the animation that updates the --wc-loaded property to 1. This prevents opacity flashing when new components are dynamically added to the page after initial load.

The Magic: Once all custom elements are registered, the :not(:defined) selector no longer matches anything, causing the body:has(:not(:defined)) condition to become false. This removes the opacity rule, and the page becomes fully visible. For fast connections, the 200ms timeout ensures minimal delay, while slow connections still show content rather than leaving users with a blank screen indefinitely.

Pros

Pure CSS solution: No JavaScript required! This means it works even in environments where JS is disabled or fails to load, and it executes immediately without waiting for the DOM or module loading.
Automatic fallback: The animation delay provides a built-in timeout. If components fail to define, the page still becomes visible after 200ms. No need for manual setTimeout calls.
Lightweight: Just a few lines of CSS - no extra scripts, no DOM queries, no Promise wrangling.
Reactive: The :has() selector automatically updates when elements become defined.
Easy to customize: Want a longer timeout? Change the animation delay. Want to target specific containers instead of the whole body? Adjust the selector. Timeouts and animation timing can be made configurable using CSS variables. It's flexible without being complicated.
Accessibility-friendly: Like the JS solution, this uses opacity rather than visibility, keeping content available to assistive technologies.

Cons

Browser support: The :has() selector is relatively new. It's supported in all modern browsers, but may not be supported in older versions. The good news is that if something is not supported, it will gracefully fail rather than crash your app.

Choosing the Timeout Length

Please keep in mind that this is blocking the visibility of the page until the components are defined or until the timeout has lapsed. The longer the delay is, the more it can negatively impact the user experience.

Here are some observations about the length of time:

Anything greater than 500 milliseconds there is a perceptible delay in the page load
Anything greater than 1 second begins to negatively affect the Core Web Vital scores, and you run the risk of subsequent opacity flashes if you have components added after the initial page load and before the timeout lapses.

I recommend keeping the timeout less than 500 milliseconds for the smoothest experience. That will allow your components and page content to load in a uniform manner without perceptible delays for the user.

If your components are taking longer than that to load, you may want to look into a combination of these solutions to provide a good user experience without negatively impacting the overall user experience for the rest of the application.

Wrapping Up

These solutions will continue to evolve, but FOUC doesn't have to be a necessary evil of using web components. With these techniques in your toolkit, you can provide smooth, accessible experiences for your users and boost those Core Web Vitals scores without sacrificing the benefits of web components.

Creating Truly Custom Events for Web Components

Burton Smith — Wed, 25 Jun 2025 12:54:38 +0000

When building web components, communication between components and their parent applications is crucial. While the built-in DOM events like click and change work well for standard interactions, custom events give you the power to create meaningful, semantic event types that are tailored for your components.

In this post, we'll explore how to extend JavaScript's Event class to create custom events that are both powerful and maintainable.

Why Extend the Event Class?

Before diving into the how, let's understand the why we would want to extend the Event class. It allows you to:

Create events with custom properties and methods
Implement type-safe event handling
Create reusable event classes across multiple components
Add meaningful default options for events

If you decide that creating custom event subclasses is not the approach you want to take, you can strongly type your events to create a good developer experience.

Basic Custom Event Extension

Let's start with a simple example. Here's how you might create a custom event for a shopping cart component:

class CartItemAddedEvent extends Event {
  // strongly type the event target
  declare target: ShoppingCart;

  // define the parameters of the event using the constructor
  constructor(item, quantity = 1) {
    // pass the event name and any options to the base Event class
    super('cart-item-added', {
      bubbles: true,
      cancelable: true,
      composed: true
    });

    // initialize public property values
    this.item = item;
    this.quantity = quantity;
    this.timestamp = new Date();
  }

  /** Get total price for added item */
  get totalPrice(): number {
    return this.item.price * this.quantity;
  }
}

// Usage in a web component
class ShoppingCart extends HTMLElement {
  addItem(item, quantity) {
    // Add item to cart logic here...

    // Dispatch custom event
    const event = new CartItemAddedEvent(item, quantity);
    this.dispatchEvent(event);
  }
}

Documenting Events

To document these custom events, we can use the @event or @fires JSDoc tags in the component class's documentation. In the description, we can also provide a type. This information will all be added to the Custom Element's Manifest. This is very helpful when creating custom integrations and type definitions for various environments.

/**
 * ... other documentation
 *
 * @event {CartItemAddedEvent} cart-item-added - emitted when an item is added to the cart
 */
class ShoppingCart extends HTMLElement {...}

Global Event Map Registration

To enable automatic type inference with addEventListener, register your custom events in the global event map:

declare global {
  interface GlobalEventHandlersEventMap {
    'cart-item-added': CartItemAddedEvent;
  }
}

Advanced Custom Event with Validation

Here's a more sophisticated example of what can be done with custom events that includes validation and error handling:

type ValidationResult = {
  isValid: boolean;
  errors: string[];
};

class FormValidationEvent extends Event {
  // strongly type the event target
  declare target: CustomForm;

  constructor(
    fieldName: string, 
    value: string, 
    validationResult: ValidationResult
  ) {
    super('form-validation', {
      bubbles: true,
      cancelable: false,
      composed: true
    });

    this.fieldName = fieldName;
    this.value = value;
    this.validationResult = validationResult;
    this.isValid = validationResult.isValid;
    this.errors = validationResult.errors || [];
  }

  static createSuccess(fieldName, value): FormValidationEvent {
    return new FormValidationEvent(fieldName, value, {
      isValid: true,
      errors: []
    });
  }

  static createError(fieldName, value, errors): FormValidationEvent {
    return new FormValidationEvent(fieldName, value, {
      isValid: false,
      errors: Array.isArray(errors) ? errors : [errors]
    });
  }

  hasError(errorType: 'tooLong' | 'invalidType' | 'required'): boolean {
    return this.errors.some(error => error.type === errorType);
  }

  getErrorMessage(): string {
    return this.errors.map(error => error.message).join(', ');
  }
}

// Usage in a form component
class CustomForm extends HTMLElement {
  validateField(fieldName, value) {
    const validationResult = this.runValidation(fieldName, value);

    // using static methods to instantiate specific event variations
    const event = validationResult.isValid 
      ? FormValidationEvent.createSuccess(fieldName, value)
      : FormValidationEvent.createError(fieldName, value, validationResult.errors);

    this.dispatchEvent(event);
  }
}

Creating Event Hierarchies

You can extend your custom events for complex component systems and set meaningful defaults in base classes to reduce repetitive code:

// Base event class
class ComponentEvent extends Event {
  constructor(type, options = {}) {
    super(type, {
      bubbles: true,
      cancelable: true,
      composed: true,
      ...options
    });

    this.timestamp = new Date();
    this.componentId = options.componentId || null;
  }
}

// Specific event types
class ComponentLoadedEvent extends ComponentEvent {
  constructor(componentId, loadTime) {
    super('component-loaded', { componentId });
    this.loadTime = loadTime;
  }
}

class ComponentErrorEvent extends ComponentEvent {
  constructor(componentId, error) {
    super('component-error', { componentId });
    this.error = error;
    this.severity = error.severity || 'error';
  }

  get isCritical() {
    return this.severity === 'critical';
  }
}

Pros and Cons of Subclassing Events

Like any engineering decision, there are trade-offs with choosing to go with a custom event class or using a standard Event or CustomEvent. Here are some pros and cons to subclassing Event that teams should take into consideration when making a decision.

Pros of Extending the Event Class

Type Safety and IntelliSense

When using TypeScript or modern IDEs, extended Event classes provide excellent autocomplete and type checking without having to create new types.

Reusability

Event classes can be imported and reused across multiple components, ensuring consistency and uniformity.

Custom Logic

You can add custom logic to your events rather than repeating it in your components.

Rich API

Custom methods and getters on your event classes provide a clean API for event consumers.

Debugging

Custom event classes make debugging easier with meaningful class names in stack traces.

Event Instance Checking

Because the events are a specific class, developers can validate the event type by using instanceof. This is very helpful if you are using event delegation by listening to events on parent elements.

someDiv.addEventListener('my-event', e => {
  if (e instanceof MyCustomEvent) {
    // logic for handling the event
  }
});

Cons of Extending the Event Class

Bundle Size

Each custom event class adds to your JavaScript bundle size (though the impact is usually minimal).

Learning Curve

Developers need to understand your custom event system, which adds complexity compared to standard DOM events.

Event Property Pollution

When creating properties and methods on a custom event, those will be collocated with the standard Event properties and methods. Teams may prefer having custom data located in a standard interface like the detail property of a CustomEvent.

Potential Overengineering

It's easy to create overly complex event hierarchies that don't provide sufficient value.

Browser Compatibility

While modern browsers support class extensions well, older browsers may encounter issues (although this is rarely a concern for modern web components in evergreen browsers).

Memory Overhead

Creating many custom event instances can use more memory than simple object literals (though this is typically negligible).

Difficult to Create Abstractions

If you are creating utilities for emitting events, it can be difficult since events will need to instantiate a custom event class. For example, a common approach with web component libraries is to create an emit utility method in a component base class that can easily be used in inherited classes.

class BaseComponent extends HTMLElement {
  emit<T = unknown>(name: string, detail?: T) {
    this.dispatchEvent(new CustomEvent<T>(name, {
      detail,
      bubbles: true,
      composed: true
    }));
  }
}

type CustomClickDetails = {
  message: string;
};

class CustomButton extends BaseComponent {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
  }

  connectedCallback() {
    const button = document.createElement('button');
    button.textContent = 'Click Me';

    // emit a custom event when the button is clicked
    button.addEventListener('click', () => {
      this.emit<CustomClickDetails>('custom-click', { message: 'Button was clicked!' });
    });
    this.shadowRoot?.appendChild(button);

    // emit a custom event when the component has loaded
    this.emit('loaded');
  }
}

Things to Keep in Mind

Keep it simple. Don't create custom events unless they add real value over CustomEvent or Event.
Include relevant data. Add properties that event listeners will need.
Don't repeat properties and methods that the user can get from the event target.
Provide meaningful default options for your events.
Document your events. Provide clear documentation about when events fire and what data they contain.

Conclusion

Extending the JavaScript Event class is a powerful technique for creating rich, semantic event systems in web components. While it adds some complexity, the benefits of type safety, reusability, and clear APIs can outweigh the costs, especially in larger applications.

Use this technique judiciously - not every interaction requires a custom event class. However, when you do need rich event data and behavior, extending Event provides a clean and maintainable solution.

If subclassing Event looks like a good fit for you, start with simple extensions and gradually build more sophisticated event systems as your component library grows.

Creating Strongly Typed Events for Web Components

Burton Smith — Thu, 19 Jun 2025 12:14:16 +0000

If you've ever tried to handle custom events from web components in TypeScript, you've probably run into this frustrating error:

const myElement = document.querySelector('my-element');

myElement.addEventListener('my-event', e => {
  // ❌ Property 'items' does not exist on type 'EventTarget'
  console.log(e.target.items);
});

This article explores how to implement strongly typed custom events that enhance the developer experience while maintaining flexibility for non-TypeScript users.

What You'll Learn

Fix TypeScript errors with custom events (5 minutes)
Set up automatic type inference for your events
Provide better event integration with React, Vue, and Angular
Write self-documenting event code

The Problem: Weakly Typed Event Information

When working with custom events in web components, developers frequently need to access properties and methods from the element that emitted the event by accessing the event target. However, TypeScript doesn't automatically infer the correct type, leading to frustrating scenarios where type safety is lost at critical integration points.

Consider this to-do list example:

export type TodoItem = {
  id: string;
  text: string;
  completed: boolean;
}

class TodoList extends HTMLElement {
  private _items: TodoItem[] = [];

  connectedCallback() {
    this.dispatchEvent(new CustomEvent('todo-ready'));
  }

  addItem(text: string) {
    const item: TodoItem = {
      id: crypto.randomUUID(),
      text,
      completed: false
    };
    this._items.push(item);

    this.dispatchEvent(new CustomEvent('todo-added', {
      bubbles: true,
      detail: { item, total: this.items.length }
    }));
  }

  toggleItem(id: string) {
    const item = this.items.find(i => i.id === id);
    if (item) {
      item.completed = !item.completed;
      this.dispatchEvent(new CustomEvent('todo-toggled', {
        bubbles: true,
        detail: { item, total: this.items.length }
      }));
    }
  }

  get items(): TodoItem[] {
    return this._items;
  }
}

customElements.define('todo-list', TodoList);

When consuming this component, developers encounter type safety issues:

const todoList = document.querySelector('todo-list');
todoList?.addEventListener('todo-added', (e) => {
  // ❌ Error: Property 'items' does not exist on type 'EventTarget'
  console.log(e.target.items);

  // ❌ Error: Property 'total' does not exist on type 'unknown'
  console.log(e.detail.total);
});

The typical workaround involves manual type assertions, which are verbose and error-prone:

todoList?.addEventListener('todo-added', (e) => {
  // ⚠️ Requires type assertions
  const target = e.target as TodoList; 
  const detail = e.detail as { item: TodoItem; total: number };

  console.log(target.items); // ⚠️ Works, but fragile
  console.log(detail.total); // ⚠️ Requires knowledge of internal structure
});

This approach creates several problems for library authors:

Poor Developer Experience: Users must remember to cast types manually
Documentation Burden: You must document event structures separately
Maintenance Overhead: Type mismatches cause runtime errors

The Solution: Strongly Typed Events

The solution involves creating a generic type system that preserves both event target types and custom event detail types. This approach provides compile-time safety without any runtime overhead.

/**
 * A generic type for strongly typing custom events with their targets
 * @template T - The type of the event target (extends EventTarget)
 * @template D - The type of the detail payload for the custom event
 */
export type TypedEvent<
  T extends EventTarget,
  D = unknown
> = CustomEvent<D> & {
  target: T;
};

Defining Component Event Types

For our TodoList component, we can create strongly typed event definitions:

/** Event detail type definition when the to-do list changes */
export type TodoChangeDetail = {
  /** The item that was added or changed */
  item: TodoItem;
  /** The total number of to-do items */
  total: number;
}

/** `TodoList` specific generic event type */
export type TodoListEvent<D = unknown> = TypedEvent<TodoList, D>;

/** The type for the change event */
export type TodoListChangeEvent = TodoListEvent<TodoChangeDetail>;

Global Event Map Registration

To enable automatic type inference with addEventListener, register your custom events in the global event map:

declare global {
  interface GlobalEventHandlersEventMap {
    'todo-ready': TodoListEvent;
    'todo-added': TodoListChangeEvent;
    'todo-toggled': TodoListChangeEvent;
  }
}

Now developers can use your events with full type safety:

const todoList = document.querySelector('todo-list');

todoList?.addEventListener('todo-added', (e) => {
  // ✅ Fully typed - no assertions needed
  console.log(e.target.items); // TodoItem[]
  console.log(e.detail.total); // number
  console.log(e.detail.item.text); // string
});

todoList?.addEventListener('todo-toggled', (e) => {
  // ✅ Different detail type automatically inferred
  console.log(e.detail.item.completed); // boolean
});

Non-unique Event Names

When using standard event names like change or input, you cannot extend the global event map due to conflicts. Instead, provide typed overloads:

// For standard events, provide explicit typing
const todoList = document.querySelector('todo-list');

todoList?.addEventListener('change', (e: TodoListChangeEvent) => {
  console.log(e.target.items); // ✅ Strongly typed
});

Documenting Events

/**
 * ... other documentation
 *
 * @event {TodoListEvent} todo-ready - emitted when the component is mounted
 * @event {TodoListChangeEvent} todo-added - emitted when a to-do item is added
 * @event {TodoListChangeEvent} todo-toggled - emitted when a to-do item is toggled
 */
class TodoList extends HTMLElement {...}

Demo

If you would like to play around with these types yourself, feel free to check out this StackBlitz.

Usage in Frameworks

Strongly typing these events can also make framework integration with your web components much easier. Here is a simple react example:

import React, { useState } from 'react';
import { TodoListChangeEvent, TodoItem } from './todo-list-types';

const TodoApp = () => {
  const [items, setItems] = useState<TodoItem[]>([]);
  const [total, setTotal] = useState(0);

  const handleTodoAdded = (event: TodoListChangeEvent) => {
    setItems(event.target.items);
    setTotal(event.detail.total);
  };

  const handleTodoToggled = (event: TodoListChangeEvent) => {
    setItems(event.target.items);
  };

  return (
    <div>
      <todo-list ontodo-added={handleTodoAdded} ontodo-toggled={handleTodoToggled}></todo-list>
      <p>Total items: {total}</p>
      <ul>
        {items.map(item => (
          <li key={item.id} style={{ 
            textDecoration: item.completed ? 'line-through' : 'none' 
          }}>
            {item.text}
          </li>
        ))}
      </ul>
    </div>
  );
};

export default TodoApp;

Benefits of Strongly Typed Custom Events

This pattern provides several key advantages:

Compile-time Safety: TypeScript catches mismatched property names and types before your code runs, preventing common runtime errors.
Enhanced Developer Experience: IDE autocomplete works perfectly, showing available properties on both the event target and detail object.
Self-Documenting Code: The type definitions serve as documentation, making it clear what data events are carried and which elements can dispatch them.
Refactoring Confidence: When you change event data structures, TypeScript will flag all locations that need updates.
Better Testing: Strongly typed events make it easier to write comprehensive tests since you know exactly what data to expect.

Conclusion

Strongly typing custom events transforms them from a potential source of bugs into a reliable, developer-friendly communication mechanism. By leveraging TypeScript's type system with patterns like the TypedEvent we created, you can build more maintainable applications with better developer experience and fewer runtime surprises.

Finding What Drives You

Burton Smith — Mon, 13 Jan 2025 18:04:18 +0000

Every year there are predictions that "'x' will massively change 'y'" or "'a' will be the death of 'b'".

AI continues to be a disruptor (for better or for worse) in many industries and one of the 2025 predictions is that "AI will be the death of the software engineer". As a software engineer, my knee-jerk reaction is to balk at the idea that AI could replace my craftsmanship. I love building software and AI appears to be positioned to threaten my livelihood and my passion.

There's no putting the proverbial AI toothpaste back in the tube. It's here to stay and here to change things. Despite that, I don't think this is an accurate prediction, but my pragmatic side made me pause and think, "Well, what if...? Would I be ok? Would I be happy? Could I find a job that I enjoy as much as I like this?". To find some sense of safety in this, I've had to do a little self-reflection to understand why I love what I do.

Finding My Drive

After I graduated high school, I was in South Korea teaching an English lesson. One of the stories in the book we were using was the allegory "The King's Highway". It's short, so I've included it here for your viewing pleasure and to help provide context.

The King's Highway

Once a king had a great highway built for the members of his kingdom. After it was completed, but before it was opened to the public, the king decided to have a contest. He invited as many as desired to participate. Their challenge was to see who could travel the highway the best.

On the day of the contest the people came. Some of them had fine chariots. Some ran along the highway and others rode horses, mules, or donkeys.

People traveled the highway all day, but each one, when he arrived at the end, complained to the king that there was a large pile of rocks and debris left on the road at one spot and this got in their way and hindered their travel.

At the end of the day, a lone traveler wearily crossed the finish line and walked over to the king. He was tired and dirty, but he addressed the king with great respect and handed him a bag of gold. He explained, "I stopped along the way to clear a pile of rocks and debris that was blocking the road. This bag of gold was under it all. I want to give it to you so you can return it to its rightful owner."

The king replied, "You are the rightful owner."

The traveler replied, "Oh no, this is not mine. I've never known such money."

"Oh yes," said the king, "you've earned this gold, for you won my contest."

"He who travels the road best is he who makes the road smoother for those who will follow."

The lesson in this story struck me deeply. It has stuck with me and I believe it has influenced my actions ever since. While I get paid as a software engineer, I don't get paid for any of my open-source projects, speaking events, or volunteering at hackathons. I'm not saying I'm above any of that, so if you'd like to pay me for those things, I'll gladly take your money. 😉 What I am saying is that I would do these things whether I was getting paid or not because I like to help smooth the road for other travelers.

What does this mean?

Making the road smoother for others is a driving force for me, and software engineering is a mechanism for me to express that. I don't believe this is the sum of who I am, but this is a way I feel I can provide value.

I have no plans to stop software engineering any time soon, but this helps me disassociate my identity from my profession. It now frees me to be open to the idea of growing beyond my trade and pivoting to something else if needed. This also allows me to feel less threatened by AI and opens me up to opportunities to embrace changes it may bring that could improve my existing experience.

Find your drive and keep making cool shit!

Deprecating Your Web Component APIs

Burton Smith — Wed, 27 Nov 2024 19:06:53 +0000

Deprecating your web component APIs is a great way to communicate to your users that a feature will be removed in the next major release of your package. If you are using a Custom Elements Manifest for documenting your component APIs, this may be trickier than it seems. Web components typically have more public APIs than framework components:

CSS variables
CSS parts
slots
events
methods
attributes
properties.

In this article, I will demonstrate how to document your API deprecations and add replacement features without introducing breaking changes.

Documentation

One of the trickiest parts of the deprecation process is the documentation. For properties, methods, and even your component, this can be as simple as adding a @deprecated tag to your JSDoc comment in the component's class.

/**
  * @deprecated This component is going away. Use ... instead.
  */
class MyElement extends HTMLElement {
  /** @deprecated This property is being removed. Use ... instead. */
  myProp;

  /** @deprecated This method is going away. Use ... instead. */
  myMethod() {
  }
}

The CSS variables, CSS parts, slots, events, and attributes are typically documented in the class's JSDoc.

Here's an example of what you can document in a custom elements JSDoc:

/**
 * @attr {boolean} disabled - disables the element
 * @attribute {string} foo - description for foo
 *
 * @csspart bar - Styles the bar element in the shadow DOM
 *
 * @slot - This is a default/unnamed slot
 * @slot container - You can put some elements here
 *
 * @cssprop --text-color - Controls the color of foo
 * @cssproperty [--background-color=red] - Controls the background color of bar
 *
 * @prop {boolean} prop1 - some description
 * @property {number} prop2 - some description
 *
 * @fires custom-event - some description for custom-event
 * @fires {MyType} typed-event - some description for typed-event
 * @event {MyType} typed-custom-event - some description for typed-custom-event
 *
 * @summary This is MyElement
 *
 * @tag my-element
 * @tagname my-element
 */
class MyElement extends HTMLElement {}

The Problem

The challenge is that you can't double up on JSDoc tags and use the @deprecated tag to indicate that these items are deprecated. Otherwise, it will be interpreted as the entire class is deprecated.

/**
 * @cssprop --text-color - @deprecated I dub thee "deprecated" ❌
 */
class MyElement extends HTMLElement {}

A Solution

To get around this, I created a tool (custom-elements-manifest-deprecator) that allows you to tag items in your JSDoc so they are appropriately updated in the Custom Elements Manifest.

Using this tool you can use alternative tags to identify deprecated APIs. By default, it uses a parenthesis-wrapped @deprecated tag as the identifier (which is what we'll use today), but it can be customized to whatever you would like.

/**
 * @cssprop --text-color - (@deprecated) I dub thee "deprecated" 👍
 */
class MyElement extends HTMLElement {}

Updating Your APIs

An important thing for our team is that when we will be removing or changing an API, we try to introduce the new feature before the next major release so teams can migrate to it early. That way, if they are staying up-to-date, they can minimize the impact of upgrading to a new version.

In this next section, we will go through how to introduce new features without breaking your old APIs and how they can co-exist without competing with each other. We will be updating some APIs for a simple button component.

In this example I will be using Lit, but these features and principles can be applied to any environment.

CSS Variables

To provide better autocomplete and descriptions in our editors like VS Code and JetBrains, we need to provide component-specific CSS variable names.

/* old variables */
--bg-color: #ccc;
--fg-color: black;

/* new variables */
--button-bg-color: #ccc;
--button-fg-color: black;

The tricky part is that teams are already using the old variables, so we need them both to work. We can do this by mapping the deprecated variables to new ones and updating our button code to only use the variables. That way, if the users are styling with the deprecated variables, they will be applied to the new variables, or users can apply values to the new variables directly.

--bg-color: #ccc;
--fg-color: black;
--button-bg-color: var(--bg-color);
--button-fg-color: var(--fg-color);

button {
  background-color: var(--button-bg-color);
  border: solid 1px var(--button-fg-color);
  color: var(--button-fg-color);
}

Now we can update our JSDoc information with the new CSS variables and add (@deprecated) to the old ones with updated descriptions.

/**
 * An example button element.
 *
 * @tag my-button
 * 
 * @cssprop [--bg-color=#ccc] - (@deprecated) (use `--button-bg-color` instead) controls the background color of the button
 * @cssprop [--fg-color=black] - (@deprecated) (use `--button-fg-color` instead) controls the foreground/text color of the button
 * @cssprop [--button-bg-color=#ccc] - controls the background color of the button
 * @cssprop [--button-fg-color=black] - controls the foreground/text color of the button
 *
 */

CSS Parts

Like our CSS variables, we want to provide namespaced names for our parts for better tooling support, so we will be replacing control with button-control. CSS parts are pretty easy since we can apply multiple parts to an element like CSS classes, so let's apply the new part name to the element alongside the other.

<button part="control button-control">
  <slot></slot>
</button>

Now we can update our JSDoc with the new part, deprecate the old part with (@deprecated), and update the description.

/**
 * An example button element.
 *
 * @tag my-button
 *
 * @csspart control - (@deprecated) (use `button-control` instead) provides a hook to style internal button element
 * @csspart button-control - provides a hook to style internal button element
 */

Slots

With the new initiatives for our components to support internationalization (i18n), we are updating some of our APIs to be more meaningful in RTL (right-to-left) languages. One thing we want to do is update our slot that is intended to display an icon before the button text from left to start without breaking the experience for projects that are already using the left slot.

We can do this by nesting the deprecated slot within the new slot. If the new slot is not being used, it will "fall back" to the old slot.

<button part="control">
  <slot name="start">
    <slot name="left"></slot>
  </slot>
  <slot></slot>
</button>

Now we can update our JSDoc with the new slot, deprecate the old slot with (@deprecated), and update the description.

/**
 * An example button element.
 *
 * @tag my-button
 * 
 * @slot the default slot adds main content to the button
 * @slot left - (@deprecated) (use the `start` slot instead) adds content before the main button content
 * @slot start - adds content before the main button content
 */

Events

For our example, we are emitting a custom focus event, but it's getting confusing for teams, so we want to add a namespaced event (my-focus). events are pretty straightforward since you can emit both events and developers can move to the new one when they get a chance.

private handleFocus() {
  this.dispatchEvent(new CustomEvent("focus", { bubbles: true }));
  this.dispatchEvent(new CustomEvent("my-focus", { bubbles: true }));
}

Now we can update our JSDoc with the new event, deprecate the old event with (@deprecated), and update the description.

/**
 * An example button element.
 *
 * @tag my-button
 * 
 * @event focus - (@deprecated) emitted when control is focused
 * @event my-focus - emitted when control is focused
 */

NOTE: Most tools accept @event and @fires for documenting events. There isn't really a difference between them.

Methods

Methods are pretty easy to add in parallel to each other and you can use the standard @deprecated tag in the method description to communicate that it's deprecated.

/** @deprecated use `newMethod` instead */
public oldMethod() {
 ...
}

/** description about this method */
public newMethod() {
  ...
}

Properties and Attributes

Properties and attributes can be documented in the class's JSDoc using the @attr/@attribute and @prop/@property tags. If you are using them, you can use the (@deprecated) tag to deprecate them in the Custom Elements Manifest, however, it's usually better to document the property directly using its own JSDoc comment. This will enable things like types and other tooling to properly identify deprecated APIs.

The nice thing is that most analyzers are pretty good about associating attributes with properties that are being defined in the component class with decorators or other configurations, so if you deprecate the property, the associated attribute will also be deprecated.

In our demo component, we have a disable attribute that we want to update to disabled to be more in line with native HTML elements.

The first thing we want to do is deprecate the old property and add our new one.

/** @deprecated Disables the button. */
@property({ type: Boolean })
disable = false;

/** Disables the button. */
@property({ type: Boolean })
disabled = false;

Now, we want to avoid having to check both properties every time we need to determine if the component is disabled. To simplify this, we can convert the deprecated property to a getter/setter and use the new property to be the source of truth.

/** @deprecated Disables the button. */
@property({ type: Boolean })
get disable(): boolean {
  return this.disabled;
}

set disable(value: boolean) {
  this.disabled = value;
}

/** Disables the button. */
@property({ type: Boolean })
disabled = false;

Now, whenever the old value is updated, it will automatically update the new value, so we only need to check the new property to determine if the component is disabled.

<button ?disabled=${this.disabled}>...</button>

Check out the completed example!

Conclusion

Changing APIs can introduce complications, but it doesn't mean you need to stop producing new features because it may involve breaking changes. Introducing new features early and deprecating old ones can be a way to provide a good developer experience (DX). This provides a path of progressive enhancement rather than forcing teams to wait and make massive changes all at once to take advantage of new features.

Do You Need to SSR Your Web Components?

Burton Smith — Fri, 22 Nov 2024 15:45:02 +0000

Web components seem to be picking up a lot of steam lately and there have been some concerns about their compatibility with client-side frameworks pre-rendering or server-side rendering client-side content on Node.js servers.

There are ways to get your components working with SRRing, but is it worth actually SSRing your web components, or is client-side rendering enough? When exploring this question, the prevalent answer is the classic "it depends".

It Depends

Two things to consider when deciding if and what you should be server-side rendering for web components.

The first is, whether or not your web components have slow operations like data fetching. In this case, it may be a good idea to load some content from the server for the initial load.

The second comes down to user experience and your user expectations. The benefits usually associated with SSRing your content are reduced dependency on JavaScript, improved SEO, and enhanced performance.

There are many ways to use web components in your applications, but for this exploration, I will be focusing the discussion on "leaf node" primitives or small "dumb" components that receive data, and render some UI like those that would be found in a design system.

Reduced JavaScript

Web components can help reduce JavaScript dependency by removing dependencies on libraries and frameworks. If your framework is executing on the server, web components can be leveraged to handle the client-side user interactivity.

An important note is that defining custom elements is part of the JavaScript DOM API, which means there is a JavaScript dependency. That may be a concern for some teams, but the good news is there are current and forthcoming ways to create them without JavaScript.

The nice thing is that the JavaScript that is used to execute custom elements is extremely efficient which can make them wicked fast! We'll discuss more about that in the performance section of this article.

Improved SEO

When content is server-side rendered, content can be pre-fetched and JavaScript can be pre-rendered which means web crawlers and SEO bots don't have to wait for your code to be loaded before indexing your content. They often won't wait for your asynchronous data to return before analyzing the page.

Fortunately, client-side rendered web components work fine for SEO, including content rendered in the shadow DOM. You can read more about it in an article I wrote last year.

Improved Performance

One of the nice things about web components is that they are parsed and rendered directly by the browser rather than having a library parse and render the UI (again, wicked fast).

Also, isolating content in the shadow DOM allows CSS and JavaScript selectors to perform more efficiently both in and out of your custom elements. Using selectors within your component allows them to stay scoped within the shadow DOM rather than querying the entire document for elements that match the parameters. Likewise, global styles and scripts skip over shadow DOM content which reduces the number of elements they need to query.

I created a simple example with a bunch of Shoelace components where they are being lazy-loaded from a CDN. I loaded the components this way to show worst-case-scenario loading performance. As you can see, it still loads quite quickly.

After many, many attempts, the worst score I could get from Lighthouse on performance was a 94 (part of this may have been from too many people watching Netflix at my house affecting CDN download times).

If these were being eager-loaded from the same server, the performance would be consistently better!

But What About FOUC???

I believe FOUC (flash of unstyled content) is a legitimate concern for web components and should be something teams should take into consideration, especially for things like layout components. While the component loads and applies the styles and JavaScript content within and around them can shift which can negatively affect the user experience.

As you can see from the example above, the reason for the lower score was due to the Cumulative Layout Shift (CLS) that occurs as the components load and render. Again, the components are being lazy-loaded from a CDN, so this will be slightly exaggerated from some typical implementations, which helps emphasize the point.

An approach I have commonly used to reduce this is to use CSS to hide elements that have yet to be defined.

:not(:defined) {
  visibility: hidden;
}

This works better than display: none; because it allows the component to continue to occupy space while it loads and shifts around, which can reduce layout shifting, but it's not great. Then I came across this article by Cory LaViska that goes into greater detail about working with custom elements and FOUC as well as providing alternative solutions. Based on this and after discussing it with others, I have settled on this solution for now.

<style>
  body:not(.wc-loaded) {
    opacity: 0;
  }
</style>

<script type="module">
  (() => {
    Promise.allSettled(
      [...document.querySelectorAll(":not(:defined)")].map((component) =>
        customElements.whenDefined(component.tagName.toLowerCase())
      )
    ).then(() => document.body.classList.add("wc-loaded"));

    // Add fallback in case a component fails to load
    setTimeout(() => document.body.classList.add("wc-loaded"), 200);
  })();
</script>

This is a very simple solution that can be tweaked and modified to meet your environment's needs. You can see how it smooths out the load experience in this example. Also, it's improved our Lighthouse score!

Conclusion

So after all this, the million-dollar question is do teams need to SSR their web components? The answer really is "it depends" and this information should be evaluated based on your application and your user's needs.

But, for most teams using web components for their design systems and other "leaf nodes" in their projects, it's probably not worth it. They already run very lean JavaScript, are tuned for performance, and work fine for SEO, so the benefits gained by trying to SSR your components may be trivial in comparison to the work it takes to get them working for each framework.

Web Components and SSR - 2024 Edition

Burton Smith — Tue, 19 Nov 2024 14:02:30 +0000

One of the biggest gripes I hear about web components is that they don't work with Server-Side Rendering. This is unfortunately a little misleading because it's only partially true. You see, there's server-side rendering and there's server-side rendering. It works in the former, but not the latter. Don't worry, I'll explain. 😉

Server-Side Rendering

There are really two kinds of server-side rendering that get conflated into the same concept. The first is server-side framework server-side rendering and client-side framework server-side rendering.

Server-Side Framework SSR

Server-side Framework SSR is when you use a framework that runs the HTML templating logic entirely on the server to compose the HTML that will be rendered in the browser. These are frameworks like Ruby on Rails, ASP.Net, PHP, or even Node.js frameworks that use templating languages like Pug or EJS.

Web components work great in this type of server-side rendering!

Client-Side Framework SSR

Client-side Framework SSR is when a frontend framework executes the client-side code on a Node.js server before sending it to the browser. This is done to reduce the amount of JavaScript that is shipped and executed in the browser.

There are some big advantages of doing this:

improve performance
better SEO
reduced dependency on JavaScript

The Problem

The problem is that this approach introduces some challenges for custom elements and other web APIs.

The first challenge is that when defining custom elements the API is window.customElements.define('my-element', MyElement). When you render client-side code on a Node.js server, guess what's missing - the window. Because of this, typical commands on the window object, and other APIs like localStorage and MutationObserver fail during SSRing.

The other challenge is that web components are interoperable, which means they can be used across frameworks like standard HTML elements, but client-side framework SSRing is not based on any standard. Each framework has its own bespoke method of executing its UI, so there is no clear approach for how and when to SSR custom elements. You need an implementation for each environment in which they are being used.

Current Solutions

You can do some things right now to use your web components with client-side framework SSRing.

Deferred Definition

The first thing you can do to get your components working right now is defer the component definition until the window object is present. Unfortunately, checking if the window exists before defining your components won't consistently work because the logic will be executed on the server and may not be run again when the code gets to the client. Most frameworks have a way to specify when code needs to be run on the "client only", so you will need to find out how to do that based on the framework you're using.

Declarative Shadow DOM (DSD)

A recent development has been the ability to define HTML templates in a shadow root declaratively. This has been dubbed declarative shadow DOM.

<my-button>
  <template shadowrootmode="open">
    <style>
      button {
        padding: 0.25rem;
        border: solid 1px black;
      }
    </style>
    <button>
      <slot></slot>
    </button>
  </template>
  My Button
</my-button>

This provides some amazing capabilities and if you defer the component definition, they can be upgraded when the client is ready. The downside is that it doesn't scale very well for something like design systems with many components. You would need to do this for every custom element on the page.

<my-button>
  <template shadowrootmode="open">
    <style>
      button {
        padding: 0.25rem;
        border: solid 1px black;
      }
    </style>
    <button>
      <slot></slot>
    </button>
  </template>
  My Button 1
</my-button>

<my-button>
  <template shadowrootmode="open">
    <style>
      button {
        padding: 0.25rem;
        border: solid 1px black;
      }
    </style>
    <button>
      <slot></slot>
    </button>
  </template>
  My Button 2
</my-button>

Teams are attempting to use this as a stop-gap for now (like @lit-labs/ssr). This often requires special code considerations like limitations on how and when you can use certain APIs, so I don't think this is an ideal solution.

WASM?

An interesting new solution from the Enhance team is that they are using WebAssembly to provide SSRing of custom elements. This is currently limited to their ecosystem, but there may be an opportunity to learn from this and try to create a more framework-agnostic approach in the future.

Future Solutions

There are some new proposals in the works that should provide a scalable solution to some of the pain points SSRing is trying to solve when it comes to web components.

Declarative Custom Elements (DCE)

Declarative Custom Elements (DCE) is a technology that may provide a more efficient approach to authoring web components. These are similar to custom elements using the Declarative Shadow DOM, but you only have to define them once and they can be used everywhere.

<template element="my-button">
  <style>
    button {
      padding: 0.25rem;
      border: solid 1px black;
    }
  </style>
  <button>
    <slot></slot>
  </button>
</template>

<my-button>My Button 1</my-button>
<my-button>My Button 2</my-button>

This, in conjunction with HTML modules would provide a mechanism for custom elements that are both client-side framework SSR-friendly, reduce the dependency on JavaScript, and improve the performance of our custom elements that don't require any JavaScript. Also, like custom elements using the Declarative Shadow DOM, these custom elements can be upgraded once the client is available for more advanced user interactions.

Conclusion

If your application uses a server-side framework to render your UIs, you are safe to use web components. If you are using a client-side framework to render your UIs, there are some things you can do now to make your components work in those scenarios, but some new things are coming that should greatly improve the experience SSR for custom elements.

Bulletproof Web Component APIs

Burton Smith — Tue, 12 Nov 2024 13:27:08 +0000

Web components/custom elements provide some great features that can make your UX more efficient and scalable, but there are some "gotchas" that can prevent teams from having a good experience with your components.

The Problem

One of the great things about custom elements/web components can sometimes be a challenge for them - they can be used anywhere. You never know if they're being used in a framework, in a type-safe environment, rendered on the server with a language like PHP, created programmatically using JavaScript's createElement function, or even in plain ol' HTML.

The challenge is that there's no consistent way to ensure your web component APIs are correctly implemented. Because of this, one of the items in our component library's PR checklist is:

✅ Attributes and properties work when set, unset, and poorly set.

For example, in our library, we have an "input" component that, like a native <input> element, has a type attribute with some specified values. It doesn't have all of the same options because we have specific components for some of the other controls like radios and checkboxes.

/** A string specifying the type of control to render. */
@property()
type:
  | 'color'
  | 'date'
  | 'email'
  | 'number'
  | 'password'
  | 'search'
  | 'tel'
  | 'text' = 'text';

NOTE: The code examples are using Lit, but the principles discussed here can be applied to other libraries and frameworks.

When we test testing this attribute, we get inconsistent results.

Set
- everything works as expected.

<my-input type="color"></my-input>
<my-input type="date"></my-input>
<my-input type="email"></my-input>
<my-input type="number"></my-input>
<my-input type="password"></my-input>
<my-input type="search"></my-input>
<my-input type="tel"></my-input>
<my-input type="text"></my-input>

Unset
- the component works fine when the attribute is not set because of the default value
- the component renders correctly when the property is undefined because the internal HTML element is resilient, but the custom logic and validation in the component break

// When the attribute is not set
<my-input></my-input>

// When the property is `undefined` (example using JSX)
<my-input type={undefined}></my-input>

Poorly set
- setting the type attribute value to "rubbish" renders a text input, but also breaks our custom logic and validation.
- setting it to a value that is a valid HTML input type, but not one that we have specified for the component, renders controls not intended for our component which not only breaks our custom logic and validation, but also our styles/designs.

<!-- not a real type -->
<my-input type="rubbish"></my-input>

<!-- we don't want users using this type -->
<my-input type="range"></my-input>

You can test this example here:

How do we fix it?

I noticed that the native HTML element seems to pass the "set, unset, and poorly set" test, so let's see if we can learn from it.

When I poorly set the native input's attribute and log the property values, I can see why it works.

<!-- set the value to a non-standard type -->
<input type="rubbish" />
<input id="undefinedInput" />

<script>
  // programmatically set the value to `undefined`
  undefinedInput.type = undefined;

  console.log(rubbishInput.type);   // logs 'text'
  console.log(undefinedInput.type); // logs 'text'
</script>

If an invalid value is assigned to the attribute or property, it falls back to a default value. We should be able to do the same and still maintain strong typing.

Let's start by creating a list of valid values and a type for our property.

const inputTypes = [
  'color',
  'date',
  'email',
  'number',
  'password',
  'search',
  'tel',
  'text',
] as const;

We can use the array to create a union type for TypeScript validation.

type InputType = typeof inputTypes[number];

Now we can update our custom elements property with some validation logic. We can do this by converting our existing property to a standard JavaScript class getter and setter.

// private property for storing the `type` property value
private _type: InputType = 'text';

/** A string specifying the type of control to render. */
@property()
set type(value: InputType) {
  // Confirming the value is in our approved list of values. If not, it will use a fallback value of "text"
  this._type = inputTypes.includes(value) ? value : 'text';
}

get type(): InputType {
  return this._type;
}

Here's our final output:

Conclusion

With this new validation in place, our input component is far more resilient than before and also allows for more complex validation if necessary. This method may also be overkill for some of your attributes, especially those that are for styling. For those scenarios, be sure to check out this article.

Don't Rely on Default Attribute Values For Styling Web Components

Burton Smith — Tue, 12 Nov 2024 13:26:48 +0000

Don't get me wrong, I have nothing against default values for web component APIs. The problem I have with them is that they are unreliable.

The Problem

A common approach for providing a list of available options for an API is using TypeScript's untion type.

/** The display variant for the button */
@property({reflect: true})
variant: 'default' | 'solid' | 'ghost' = 'default';

Here is some basic CSS to make the variations work.

:host {
  --accent-color: #0265dc;
}

button {
  cursor: pointer;
  padding: 0.5rem;
}

:host([variant='default']) button {
  border: solid 1px var(--accent-color);
  background-color: white;
  color: var(--accent-color);
}

:host([variant='solid']) button {
  border: solid 1px var(--accent-color);
  background-color: var(--accent-color);
  color: white;
}

:host([variant='ghost']) button {
  border: solid 1px transparent;
  background-color: transparent;
  color: var(--accent-color);
}

NOTE: The code examples are using Lit, but the principles discussed here can be applied to other libraries and frameworks.

The challenge is custom elements/web components can be used anywhere. They can be inserted in the DOM in strings, in server-side languages like PHP, they can be created in JavaScript's createElement function, or even in standard HTML. What I'm getting at is that there is not always a "type-safe" way to ensure custom element attributes are being set accurately. Because of this, one of the items in our component library's PR checklist is:

✅ Attributes and properties work when set, unset, and poorly set.

Testing Our API

Given these guidelines, let's test the API setup above.

Set - everything looks good.

<my-button variant="default">Default Button</my-button>
<my-button variant="solid">Solid Button</my-button>
<my-button variant="ghost">My Button</my-button>

Unset
- without an attribute set it works fine because we have a default value and it is configured to reflect the attribute on the element when it is set.
- if we set the variant property to undefined, it breaks the styles.

<!-- No attribute set -->
<my-button>No Attribute Button</my-button>

<!-- JSX example -->
<my-button variant={undefined}>Unset Button</my-button>

Poorly set - when we set the variant attribute to "rubbish" it also breaks.

<my-button variant="rubbish">Rubbish Button</my-button>

You can test this example here:

Fixing the API

The easiest way to fix this is to make the button element styles match the default styles.

button {
  border: solid 1px var(--accent-color);
  background-color: white;
  color: var(--accent-color);
  cursor: pointer;
  padding: 0.5rem;
}

Now we can remove the code for the default variation.

/* We can remove this */
:host([variant='default']) button {
  border: solid 1px var(--accent-color);
  background-color: white;
  color: var(--accent-color);
}

To avoid confusion, you can leave the style and add a comment.

/* Styles for this variant are under the `button` element */
:host([variant='default']) { }

Let's also update the TypeScript API to make it optional and remove the default value.

/** The display variant for the button */
@property({ reflect: true })
variant?: 'default' | 'solid' | 'ghost';

The elements now behave consistently if the value is set, unset, or poorly set!

You can see the final code here:

Conclusion

By removing a dependency on default values, you can create more resilient web component APIs. If you must have default values for your components to function properly, be sure to check out this article to create web components that work consistently.

You Should Be Shipping a Manifest with Your Web Components

Burton Smith — Thu, 07 Nov 2024 13:48:16 +0000

Besides your components, the Custom Elements Manifest is the most important thing you can ship in your library.

What is a Custom Elements Manifest (CEM)?

The Custom Elements Manifest is a schema designed to document the metadata about your custom elements/web components, including attributes, properties, methods, events, slots, CSS parts, and CSS variables. It takes all of the information about your components and serializes it into a single json file in your project.

Why do users need it?

This standardized documentation method unlocks huge possibilities with how teams use and interact with your component library. Developers can use it for documentation purposes like Adobe Spectrum's API documentation.

Teams can also use them for framework, IDE integrations, and other tooling like Storybook.

This is nice if you want to create specific types or framework integrations you would like to ship with your components, but it's tough to anticipate all of your user's needs. You may be building your components to be used in a Vue.js environment, but another team may come along that needs to use your components in a react environment. Rather than waiting for you to build and ship react wrappers, teams can use the CEM to generate their own wrappers locally.

A recent example of this was when I was helping a team get up and running with Shoelace in a Next.js application. Shoelace provides react wrappers, but they were throwing an error when Next.js tried to server-side render them. Fortunately, Shoelace ships their CEM, so I was able to use it to generate new wrappers that were SSR-safe.

Here is a link to an example:

How do you create a CEM?

There are a couple of tools out there for creating a CEM (web-component-analyzer and Lit labs has an experimental tool), but my go-to tool is the Custom Elements Manifest Analyzer.

This is a great option for a few reasons reasons:

It supports multiple frameworks
It has a great plugin system for developers to extend the functionality of the analyzer
Not only is it easy to use, but it also has great documentation and community support

Here are some available plugins I've created that can help improve your custom element adoption:

IDE Integrations
- VS Code Integration
- JetBrains IDE Integration
JS Framework Integrations

NOTE: These provide CEM Analyzer plugins and functions for pre-generated CEMs. If you're not using the CEM Analyzer, don't worry, you can still take advantage of these.

Conclusion

The Custom Element Manifest is a great tool for accelerating user adoption of your custom element component library. By providing it as part of your product, you can provide consumers with the means to ensure their needs are being met when using your custom elements.

When choosing a library or framework for authoring your custom elements, it's a good idea to try to find one that you can generate a CEM, especially if your components will be used by other teams.

Dark Mode in Web Components is About to Get AWESOME!

Burton Smith — Wed, 17 Apr 2024 01:29:05 +0000

You may think the title of this article is hyperbole, but I assure you what is coming for managing "dark mode" in web components is about to get awesome. Before we get into the solutions, let's talk about the problem.

The Problem

When working with light and dark mode themes today we typically have two approaches to solving the problem - using media queries and using a theme switcher/toggle.

Using Media Queries

The first is with the prefers-color-scheme media query and CSS custom properties. Colors and styles are defined one way for "light mode" and again within a media query for "dark mode".

This method allows us to provide styles based on the user's system preferences, but leads to large CSS files and makes it difficult to manage the theme globally or at a component level (for example, if we wanted to create an "inverted" nav bar) because it's difficult to force the color scheme to change.

NOTE: In addition to the many benefits of CSS custom properties, it is important to note that they are inheritable across shadow roots, which makes them fantastic tools for managing design tokens in a web component library.

Using a Theme Switcher

Another scenario is when sites provide a theme toggle so users can choose between light and dark modes, but also allow it to fall back to user preferences if one isn't selected. This usually requires defining styles scoped to "light-mode" and "dark-mode" class names and some JavaScript to check the user's system preferences to set the user hasn't been specified.

This can introduce FOWC - Flash of Wrongly-styled Content (yes, I just made that up) - while the browser loads and parses the JavaScript. It also makes it very inconvenient to understand what "mode" our project is in within the shadow DOM.

Enter `light-dark()` CSS Function

light-dark() is a new CSS color function that allows us to define light and dark mode colors in a single property without needing to redefine our properties in a media query or alternative class name. With this new function, we can simplify the implementation by not having to define the style in two different places.

This example provides the same functionality as the first example with the media query, but with significantly less code and is much easier to maintain.

If we use a design token system, this can be used with CSS custom properties (variables) to create other CSS custom properties.

--button-bg-color: light-dark(var(--light-color), var(--dark-color));

Using `color-scheme`

If we want to add the theme switcher capability, we can do so with just a few lines of CSS. The CSS color-scheme property allows us to dictate to the browser which color scheme to use. This is nice because it not only uses the light and dark colors defined in the light-dark() function but also the browser's native light and dark mode colors.

Composing Web Components

Let's add a web component into the mix and see what happens. In this example, the web component requires different colors than the global button colors we originally defined.

One of the best parts about this is that the color-scheme value is inheritable across the shadow root, meaning the code in our shadow DOM can be context-aware of the color scheme!

Creating Themable Components

Not only can the components be aware of the color scheme, but we can also dictate it based on the component's API.

Considerations

At the time of writing this article, the light-dark() function is in the beta release of Safari. It also looks like the MDN browser compatibility info and caniuse.com are not accurate. These work in both Edge and Opera.

Conclusion

With these new CSS features, our ability to style content in and outside our web components will significantly improve. We can get more features than we have today with much less code that is more performant and compatible with the native browser APIs.