Web Components: Custom Elements Guide

Introduction to Web Components

Web Components are a set of native browser APIs that let developers create reusable, encapsulated HTML elements. Unlike framework-specific components that only work within their ecosystem, Web Components are built on web standards and work everywhere, in React, Angular, Vue, or plain HTML. This guide covers everything you need to build production-ready custom elements.

The Three Pillars of Web Components

Custom Elements

Custom Elements allow you to define new HTML tags with their own behavior and lifecycle. By extending the HTMLElement class, you create elements that the browser treats as first-class citizens, complete with lifecycle callbacks for creation, connection, attribute changes, and destruction.

Shadow DOM

Shadow DOM provides style and markup encapsulation. Elements inside a shadow root are isolated from the rest of the document, meaning external CSS cannot accidentally break your component, and your component's styles do not leak out. This encapsulation is critical for building reliable, portable components.

HTML Templates

The template and slot elements provide a mechanism for defining inert markup that can be stamped out on demand. Templates are parsed but not rendered until explicitly cloned and inserted into the DOM, making them efficient for component rendering patterns.

Creating Your First Custom Element

Basic Structure

A custom element is a JavaScript class that extends HTMLElement. You register it with the browser using customElements.define(), providing a tag name that must contain a hyphen to distinguish it from native HTML elements.

Lifecycle Callbacks

Custom elements have four key lifecycle callbacks:

1. connectedCallback: Called when the element is added to the DOM. This is where you initialize content, attach event listeners, and start rendering.
2. disconnectedCallback: Called when the element is removed from the DOM. Use this for cleanup like removing event listeners and stopping timers.
3. attributeChangedCallback: Triggered when an observed attribute changes. This enables reactive behavior based on attribute values.
4. adoptedCallback: Called when the element is moved to a new document, which is rare but useful for iframe scenarios.

Working with Shadow DOM

Open vs Closed Shadow Roots

Shadow roots can be created in two modes:

• Open: The shadow root is accessible via element.shadowRoot. This is the recommended default for most use cases.
• Closed: The shadow root is not externally accessible. While this provides stronger encapsulation, it complicates testing and debugging.

Styling Inside Shadow DOM

Styles defined within a shadow root are scoped to that shadow tree. However, several mechanisms allow controlled style interaction:

• CSS custom properties: Inherit through shadow boundaries, enabling theming
• ::part pseudo-element: Allows external styling of explicitly exposed parts
• ::slotted pseudo-element: Styles distributed children in slots
• :host selector: Styles the component's outer element from within

Slots and Content Distribution

Slots allow component consumers to inject content into predefined locations within your component. Named slots enable multiple injection points, while the default slot captures any unassigned content.

Communication Patterns

Properties vs Attributes

Attributes are string-based HTML attributes, while properties are JavaScript values on the element object. Best practice is to reflect attributes to properties and vice versa for simple values, and use properties exclusively for complex data types like objects and arrays.

Custom Events

Web Components communicate upward through the DOM using Custom Events. Create events with new CustomEvent(), specifying a name, detail data, and whether the event should bubble and compose through shadow boundaries.

Event Bubbling Through Shadow DOM

By default, events stop at shadow boundaries. To allow events to cross shadow roots, set both bubbles and composed to true when dispatching custom events. This is essential for components nested within other components.

Framework Integration

One of the greatest strengths of Web Components is their framework compatibility. At Ekolsoft, we build shared component libraries as Web Components to ensure they work across all projects regardless of the frontend framework in use.

• React: Requires wrapper components for event handling but works well for rendering
• Angular: Excellent native support through CUSTOM_ELEMENTS_SCHEMA
• Vue: Strong built-in support with automatic property/attribute handling
• Svelte: Seamless integration as Web Components are just HTML elements

Libraries and Tools

While vanilla Web Components work well, libraries simplify common patterns:

• Lit: Lightweight library from Google with reactive properties and efficient rendering
• Stencil: Compiler that generates standard Web Components with TypeScript support
• FAST Element: Microsoft's performant Web Component library
• Shoelace: Complete component library built entirely on Web Components

Best Practices

Performance

• Defer heavy initialization to connectedCallback rather than the constructor
• Use lazy rendering for components not immediately visible
• Batch DOM updates to minimize reflows
• Consider using Constructable Stylesheets for shared styles

Accessibility

• Use ARIA attributes and roles appropriately within shadow DOM
• Ensure keyboard navigation works correctly
• Delegate focus into shadow roots when needed
• Test with screen readers to verify accessibility

Web Components represent the web platform's answer to component-based development. By building on standards rather than frameworks, they offer a durability and portability that no framework-specific approach can match.

Conclusion

Web Components provide a standards-based foundation for building reusable UI elements that work across frameworks and stand the test of time. By mastering Custom Elements, Shadow DOM, and HTML Templates, developers can create encapsulated, portable components that integrate seamlessly into any web project. As Ekolsoft continues to build scalable web solutions, Web Components remain a key technology in our architecture decisions.