Component API

Custom Element

Svelte components can also be compiled to custom elements (aka web components) using the customElement: true compiler option. You should specify a tag name for the component using the <svelte:options> element.

        <svelte:options tag="my-element" />

<script>
	export let name = 'world';
</script>

<h1>Hello {name}!</h1>
<slot></slot>

Alternatively, use tag={null} to indicate that the consumer of the custom element should name it.

        import MyElement from './MyElement.svelte';

customElements.define('my-element', MyElement);

Once a custom element has been defined, it can be used as a regular DOM element:

        document.body.innerHTML = `
	<my-element>
		<p>This is some slotted content</p>
	</my-element>
`;

By default, custom elements are compiled with accessors: true, which means that any props are exposed as properties of the DOM element (as well as being readable/writable as attributes, where possible).

To prevent this, add accessors={false} to <svelte:options>.

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

// get the current value of the 'name' prop
console.log(el.name);

// set a new value, updating the shadow DOM
el.name = 'everybody';

Custom elements can be a useful way to package components for consumption in a non-Svelte app, as they will work with vanilla HTML and JavaScript as well as most frameworks. There are, however, some important differences to be aware of:

Styles are encapsulated, rather than merely scoped. This means that any non-component styles (such as you might have in a global.css file) will not apply to the custom element, including styles with the :global(...) modifier
Instead of being extracted out as a separate .css file, styles are inlined into the component as a JavaScript string
Custom elements are not generally suitable for server-side rendering, as the shadow DOM is invisible until JavaScript loads
In Svelte, slotted content renders lazily. In the DOM, it renders eagerly. In other words, it will always be created even if the component's <slot> element is inside an {#if ...} block. Similarly, including a <slot> in an {#each ...} block will not cause the slotted content to be rendered multiple times
The let: directive has no effect
Polyfills are required to support older browsers