You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
svelte/documentation/docs/02-template-syntax/09-special-elements.md

6.4 KiB

title
Special elements

Some of Svelte's concepts need special elements. Those are prefixed with svelte: and listed here.

<svelte:self>

The <svelte:self> element allows a component to include itself, recursively.

It cannot appear at the top level of your markup; it must be inside an if or each block or passed to a component's slot to prevent an infinite loop.

<script>
	/** @type {number} */
	export let count;
</script>

{#if count > 0}
	<p>counting down... {count}</p>
	<svelte:self count={count - 1} />
{:else}
	<p>lift-off!</p>
{/if}

<svelte:component>

<svelte:component this={expression} />

The <svelte:component> element renders a component dynamically, using the component constructor specified as the this property. When the property changes, the component is destroyed and recreated.

If this is falsy, no component is rendered.

<svelte:component this={currentSelection.component} foo={bar} />

<svelte:element>

<svelte:element this={expression} />

The <svelte:element> element lets you render an element of a dynamically specified type. This is useful for example when displaying rich text content from a CMS. Any properties and event listeners present will be applied to the element.

The only supported binding is bind:this, since the element type-specific bindings that Svelte does at build time (e.g. bind:value for input elements) do not work with a dynamic tag type.

If this has a nullish value, the element and its children will not be rendered.

If this is the name of a void element (e.g., br) and <svelte:element> has child elements, a runtime error will be thrown in development mode.

<script>
	let tag = 'div';

	export let handler;
</script>

<svelte:element this={tag} on:click={handler}>Foo</svelte:element>

Svelte tries its best to infer the correct namespace from the element's surroundings, but it's not always possible. You can make it explicit with an xmlns attribute:

<svelte:element this={tag} xmlns="http://www.w3.org/2000/svg" />

<svelte:window>

<svelte:window on:event={handler} />
<svelte:window bind:prop={value} />

The <svelte:window> element allows you to add event listeners to the window object without worrying about removing them when the component is destroyed, or checking for the existence of window when server-side rendering.

Unlike <svelte:self>, this element may only appear at the top level of your component and must never be inside a block or element.

<script>
	/** @param {KeyboardEvent} event */
	function handleKeydown(event) {
		alert(`pressed the ${event.key} key`);
	}
</script>

<svelte:window on:keydown={handleKeydown} />

You can also bind to the following properties:

  • innerWidth
  • innerHeight
  • outerWidth
  • outerHeight
  • scrollX
  • scrollY
  • online — an alias for window.navigator.onLine
  • devicePixelRatio

All except scrollX and scrollY are readonly.

<svelte:window bind:scrollY={y} />

Note that the page will not be scrolled to the initial value to avoid accessibility issues. Only subsequent changes to the bound variable of scrollX and scrollY will cause scrolling. However, if the scrolling behaviour is desired, call scrollTo() in onMount().

<svelte:document>

<svelte:document on:event={handler} />
<svelte:document bind:prop={value} />

Similarly to <svelte:window>, this element allows you to add listeners to events on document, such as visibilitychange, which don't fire on window. It also lets you use actions on document.

As with <svelte:window>, this element may only appear the top level of your component and must never be inside a block or element.

<svelte:document on:visibilitychange={handleVisibilityChange} use:someAction />

You can also bind to the following properties:

  • activeElement
  • fullscreenElement
  • pointerLockElement
  • visibilityState

All are readonly.

<svelte:body>

<svelte:body on:event={handler} />

Similarly to <svelte:window>, this element allows you to add listeners to events on document.body, such as mouseenter and mouseleave, which don't fire on window. It also lets you use actions on the <body> element.

As with <svelte:window> and <svelte:document>, this element may only appear the top level of your component and must never be inside a block or element.

<svelte:body on:mouseenter={handleMouseenter} on:mouseleave={handleMouseleave} use:someAction />

<svelte:head>

<svelte:head>...</svelte:head>

This element makes it possible to insert elements into document.head. During server-side rendering, head content is exposed separately to the main html content.

As with <svelte:window>, <svelte:document> and <svelte:body>, this element may only appear at the top level of your component and must never be inside a block or element.

<svelte:head>
	<title>Hello world!</title>
	<meta name="description" content="This is where the description goes for SEO" />
</svelte:head>

<svelte:options>

<svelte:options option={value} />

The <svelte:options> element provides a place to specify per-component compiler options, which are detailed in the compiler section. The possible options are:

  • immutable={true} — you never use mutable data, so the compiler can do simple referential equality checks to determine if values have changed
  • immutable={false} — the default. Svelte will be more conservative about whether or not mutable objects have changed
  • accessors={true} — adds getters and setters for the component's props
  • accessors={false} — the default
  • namespace="..." — the namespace where this component will be used, most commonly "svg"; use the "foreign" namespace to opt out of case-insensitive attribute names and HTML-specific warnings
  • customElement={...} — the options to use when compiling this component as a custom element. If a string is passed, it is used as the tag option
<svelte:options customElement="my-custom-element" />