Build Web Components with Svelte

Create reusable, framework-agnostic custom elements using Svelte's powerful customElement compiler option

Web components represent one of the most powerful features of the modern web platform, allowing developers to create reusable custom elements that work across any framework or plain HTML page. However, building web components with vanilla JavaScript requires significant boilerplate code and deep understanding of browser APIs. Svelte changes this paradigm by offering native support for compiling components into standard web components with minimal configuration. In this guide, you'll learn how to leverage Svelte's customElement compiler option to build, package, and deploy portable web components that integrate seamlessly with any web development project.

Understanding Web Components and the Platform API

Web components are a set of web platform APIs that allow you to create reusable custom HTML elements. The specification includes:

  • Custom Elements: Define your own HTML tags by extending HTMLElement
  • Shadow DOM: Create encapsulated DOM trees with isolated styling
  • HTML Templates: Reusable markup fragments with efficient cloning

The Web Components API starts deceptively simple but quickly becomes complex when building production-ready components. To create a custom element, you extend the HTMLElement class and define lifecycle callbacks:

  • connectedCallback: Invoked when the element is added to the DOM
  • attributeChangedCallback: Invoked when observed attributes change
  • disconnectedCallback: Invoked when the element is removed from the DOM

Key challenges include managing event listener cleanup, handling attribute-to-property synchronization, and manually updating the DOM when state changes. This boilerplate quickly grows even for simple components. As Mainmatter's guide to vanilla web components demonstrates, the complexity escalates rapidly.

Vanilla Web Component Example
1class CounterComponent extends HTMLElement {2 #count = 0;3 #preSentence = "";4 #btn;5 #controller;6 static observedAttributes = ["count", "pre-sentence"];7 8 constructor() {9 super();10 }11 12 attributeChangedCallback(attribute, old_value, new_value) {13 if (attribute === "count") {14 this.#count = parseInt(new_value);15 } else if (attribute === "pre-sentence") {16 this.#preSentence = new_value;17 }18 if (this.#btn) {19 this.#btn.textContent = `${this.#preSentence} ${this.#count}`;20 }21 }22 23 connectedCallback() {24 const shadow = this.attachShadow({ mode: "open" });25 this.#controller = new AbortController();26 this.#btn = document.createElement("button");27 this.#btn.textContent = `${this.#preSentence} ${this.#count}`;28 this.#btn.addEventListener(29 "click",30 () => {31 this.#count++;32 this.#btn.textContent = `${this.#preSentence} ${this.#count}`;33 },34 { signal: this.#controller.signal }35 );36 const style = document.createElement("style");37 style.innerHTML = `button{all: unset;border-radius:100vmax;background:#ff3e00;color:#111;padding:0.5rem 1rem;cursor:pointer;font-family:monospace;}`;38 shadow.append(style);39 shadow.append(this.#btn);40 }41 42 disconnectedCallback() {43 this.#controller.abort();44 }45}46 47customElements.define("counter-component", CounterComponent);

Why Svelte Excels at Web Components

Svelte compiles components to efficient imperative code that updates the DOM directly. When configured with the customElement option, Svelte wraps your component logic in a class that handles all the boilerplate of the Web Components API automatically:

  • No manual lifecycle management
  • Automatic attribute-to-property synchronization
  • Built-in event handling and cleanup
  • Declarative component definition

As Mainmatter explains, Svelte allows you to build components "in the same simple way with just a bit of configuration."

Setting Up Your Svelte Web Component Project

Using the Svelte Web Component Template

The recommended approach to start building web components with Svelte uses a specialized template that includes Vite configuration optimized for web component builds. As Lukas White's comprehensive tutorial demonstrates, the template approach provides the cleanest starting point. For teams exploring modern JavaScript frameworks and build tools, understanding how Vite integrates with Svelte provides valuable context for full-stack web development workflows.

To scaffold your project:

npx degit https://github.com/dariuszsikorski/svelte-webcomponent my-web-component
cd my-web-component
npm install

The template provides:

  • Vite configuration optimized for web component builds
  • TypeScript support with appropriate compiler options
  • A development server with hot reloading
  • Build scripts that generate distributable JavaScript

Project Structure

Components with the .wc.svelte extension in the src/wc directory are compiled as custom elements. The web-components.ts file imports and exports these components for registration.

Key Svelte Web Component Features

Automatic Registration

Components register themselves when the JavaScript loads

Props Mapping

Type-safe props with automatic HTML attribute synchronization

Shadow DOM

Style encapsulation prevents external CSS from affecting your components

Event Handling

Custom events bubble through shadow DOM boundary naturally

Slot Support

Consumers can pass content using standard slot elements

Simple Svelte Web Component
1<svelte:options customElement="fancy-button" />2 3<button onclick={() => alert("I'm super fancy actually! 😎")}>4 I'm fancy5</button>

Configuring Props and Attributes

To accept data from the outside world, define props using $props() and configure their mapping to HTML attributes:

<svelte:options customElement={{
 tag: "counter-component",
 props: {
 count: { type: "Number" },
 preSentence: { attribute: "pre-sentence" }
 }
}} />

<script>
 let { count, preSentence } = $props();
</script>

<button onclick={() => count++}>
 {preSentence} {count}
</button>

This configuration automatically creates getters and setters that sync with HTML attributes. Svelte handles parsing and typecount="10"in HTML correctly initializes the prop as conversion, so a number. As Mainmatter explains in their props handling guide, this automatic synchronization eliminates significant boilerplate.

Complete Counter Component Example
1<svelte:options css="injected" customElement={{2 tag: "counter-component",3 props: {4 count: { type: "Number" },5 preSentence: { attribute: "pre-sentence" }6 }7}} />8 9<script>10 let { count = 0, preSentence = "Count" } = $props();11</script>12 13<style>14 button {15 all: unset;16 border-radius: 100vmax;17 background-color: #ff3e00;18 color: #111;19 padding: 0.5rem 1rem;20 cursor: pointer;21 font-family: monospace;22 }23</style>24 25<button onclick={() => count++}>26 {preSentence} {count}27</button>

Styling Web Components with Svelte

CSS Injection Options

By default, Svelte component styles stay scoped to the component. For web components, you have additional options via the css attribute:

<svelte:options css="injected" customElement="my-component" />

With "injected" mode, styles are embedded directly in the shadow DOM, ensuring they apply even when the component is used in non-Svelte applications. This is the recommended approach for portable web components. Lukas White's CSS guide provides detailed considerations for styling strategies. For teams implementing comprehensive design systems, understanding style encapsulation is essential for maintainable web applications.

Style Isolation Considerations

Shadow DOM provides natural style isolation, but be aware of inheritance. Some CSS properties like font-family and color inherit through the shadow boundary. Explicitly set or reset these properties when you need consistent styling.

Building and Deploying Your Web Components

Production Build Configuration

The build process generates optimized JavaScript bundles suitable for distribution. Configure your package.json:

{
 "main": "dist/my-component.js",
 "module": "dist/my-component.js",
 "types": "dist/index.d.ts"
}

Using Your Web Components

Include the compiled JavaScript in any HTML page:

<script type="module" src="/path/to/my-component.js"></script>
<my-component prop="value"></my-component>

The script automatically registers all custom elements. No framework dependencies are required in the consuming application.

Integration with Frameworks

Web components work with any framework. Each has specific patterns:

  • React: Use wrapper components for prop synchronization
  • Vue: Built-in support with kebab-case prop mapping
  • Angular: Configure CUSTOM_ELEMENTS_SCHEMA

For teams working with React applications, web components can integrate seamlessly with proper wrapper components that handle prop type conversion and event forwarding.

Limitations and When to Use Web Components

Web components aren't always the right solution despite their platform-native nature. Key limitations include the challenges outlined in Mainmatter's analysis of web component trade-offs:

  • Server-side rendering requires additional tooling and isn't automatic
  • Complex props require JSON stringification to pass non-primitive values
  • Bundle size may be larger than framework-specific components
  • Framework interoperability has subtle quirks in each direction

When to Use Web Components

Use web components when:

  • You need truly portable components that work across projects
  • You're integrating Svelte components into non-Svelte applications
  • Building a design system for multi-framework consumption
  • Creating standalone interactive widgets for any website

When to Avoid

Consider standard Svelte components when:

  • Building a full application (use SvelteKit instead)
  • Server-side rendering is critical (SSR requires more setup)
  • Bundle size is the primary concern (runtime adds overhead)

For teams building full-stack applications, the component-based architecture of Svelte works well within SvelteKit, though standalone web components may be overkill unless you need cross-framework portability.

Frequently Asked Questions

Do I need the Svelte runtime in my consuming app?

No. The compiled web component bundle includes everything needed to run. The Svelte runtime is bundled with your component.

Can I use Svelte stores across web components?

Stores won't work across separate custom element instances since each has its own isolated scope.

How do I handle form submission?

Implement the ElementInternals API for form participation, including validation and submission callbacks.

Can I use slots with named sections?

Yes. Named slots work exactly like in regular Svelte components: `<slot name="header" />` and `<span slot="header">Title</span>`.

Conclusion

Svelte's customElement compiler option democratizes web component development by handling the boilerplate of the Web Components API automatically. By following the patterns and practices outlined in this guide, you can build reusable, portable components that leverage modern web standards while maintaining Svelte's excellent developer experience.

The combination of Svelte's compile-time optimization and web components' platform-native nature creates a powerful approach for building shareable UI components that work anywhere. Whether you're building a design system for your organization or creating interactive widgets for client projects, Svelte web components provide the flexibility and portability modern web development demands.

If you're exploring component-based development across different frameworks, consider how Svelte's approach to web components complements your overall web development strategy and integrates with your existing technology stack.

Sources

  1. Lukas White: Building Web Components with Svelte - Comprehensive guide covering project setup using Vite and the svelte-webcomponent template
  2. Mainmatter: How to Build Web Components with Svelte - In-depth tutorial explaining Web Components API fundamentals and Svelte's customElement compiler option
  3. MDN: Web Components - Official documentation on the Web Components specification