<svelte:window> event listener example
Example of using <svelte:window> with an event listener: <script> function handleKeydown(event) { alert(`pressed the ${event.key} key`); } </script> <svelte:window onkeydown={handleKeydown} />
Svelte · Language · all subjects
core/special-elements
65 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
<svelte:window> element syntax
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. Syntax: <svelte:window onevent={handler} /> for events or <svelte:window bind:prop={value} /> for property bindings. This element may only appear at the top level of your component and cannot be inside a block or element.
<svelte:window> bindable properties
The <svelte:window> element allows binding to the following window properties: innerWidth, innerHeight, outerWidth, outerHeight, scrollX, scrollY, online (an alias for window.navigator.onLine), and devicePixelRatio. All except scrollX and scrollY are readonly. Example: <svelte:window bind:scrollY={y} />
<svelte:window> scrollX and scrollY binding behavior
When binding to scrollX and scrollY, the page will not be scrolled to the initial value to avoid accessibility issues. Only subsequent changes to the bound variable will cause scrolling. If you need to scroll when the component is rendered, call scrollTo() in an $effect.
<svelte:boundary> server-side rendering with transformError
By default, error boundaries have no effect on the server—if an error occurs during rendering, the render fails entirely. Since version 5.51, you can control this behavior for boundaries with a failed snippet by calling render() with a transformError function. The transformError function must return a JSON-stringifiable object that will be used to render the failed snippet and serialized for browser hydration. If transformError throws or rethrows an error, render() fails with that error. The mount and hydrate functions also accept a transformError option, which defaults to the identity function.
<svelte:boundary> transformError security consideration
Errors that occur during server-side rendering can contain sensitive information in the message and stack properties. It is recommended to redact these rather than sending them unaltered to the browser.
<svelte:boundary> onerror with deserialized error on hydration
If the boundary has an onerror handler, it will be called upon hydration with the deserialized error object that was transformed and serialized on the server.
<svelte:boundary> overview and purpose
The <svelte:boundary> special element allows you to wall off parts of your app to provide UI for pending await expressions and handle errors during rendering or while running effects. A boundary requires one or more of the following: a pending snippet, a failed snippet, or an onerror handler. If a boundary handles an error, its existing content will be removed. Errors occurring outside the rendering process (in event handlers, setTimeout, or async work) are not caught by error boundaries.
<svelte:boundary> introduced in version 5.3.0
The <svelte:boundary> special element was added in Svelte version 5.3.0.
<svelte:boundary> pending snippet
The pending snippet is shown when the boundary is first created and remains visible until all await expressions inside the boundary have resolved. The pending snippet will not be shown for subsequent async updates; use $effect.pending() for those instead. The pending snippet must be declared either explicitly as a property or implicitly inside the boundary.
<svelte:boundary> failed snippet
The failed snippet is rendered when an error is thrown inside the boundary. It receives two arguments: error (the thrown error) and reset (a function that recreates the boundary contents). The failed snippet can be declared explicitly as a property or implicitly inside the boundary.
<svelte:boundary> onerror handler
The onerror handler is called with error and reset arguments when an error occurs inside the boundary. It is useful for tracking errors with error reporting services or capturing error and reset outside the boundary to show custom UI. If an error occurs inside the onerror function or if you rethrow the error, it will be handled by a parent boundary if one exists.
svelte:document bindable properties
You can bind to the following readonly properties on svelte:document: activeElement, fullscreenElement, pointerLockElement, and visibilityState.
svelte:document element purpose
The svelte:document element allows you to add listeners to events on document (such as visibilitychange) that don't fire on window. It also lets you use attachments on document.
svelte:document placement rules
The svelte:document element may only appear at the top level of a component and must never be inside a block or element.
svelte:document syntax with event handlers
You can attach event handlers to svelte:document using the onevent={handler} syntax, such as onvisibilitychange={handleVisibilityChange}.
svelte:document bind syntax
You can bind to document properties using the syntax bind:prop={value}, such as bind:visibilityState={state}.
svelte:body placement rules
The <svelte:body> element may only appear at the top level of your component and must never be inside a block or element.
svelte:body with event listeners and actions
You can attach multiple event handlers to <svelte:body> using the onevent={handler} syntax and apply actions using the use: directive, as in <svelte:body onmouseenter={handleMouseenter} onmouseleave={handleMouseleave} use:someAction />.
svelte:body element syntax
The <svelte:body> element uses the syntax <svelte:body onevent={handler} /> and allows you to add listeners to events on document.body, such as mouseenter and mouseleave, which do not fire on window. It also lets you use actions on the <body> element.
<svelte:head> placement restrictions
<svelte:head> may only appear at the top level of a component and must never be inside a block or element, consistent with <svelte:window>, <svelte:document>, and <svelte:body>.
<svelte:head> special element
<svelte:head> is a special element that allows inserting elements into document.head. During server-side rendering, head content is exposed separately from the main body content.
<svelte:head> example with title and meta tags
The <svelte:head> element can wrap elements like <title> and <meta> tags. For example: <svelte:head><title>Hello world!</title><meta name="description" content="This is where the description goes for SEO" /></svelte:head>
Deprecated Svelte 4 options in svelte:options
The following options are deprecated in Svelte 5 and non-functional in runes mode: immutable={true} (tells compiler you never use mutable data for simple referential equality checks), immutable={false} (the default, more conservative checks), accessors={true} (adds getters and setters for component props), accessors={false} (the default).
svelte:options element syntax
The <svelte:options> element provides a place to specify per-component compiler options. It uses the syntax <svelte:options option={value} />.
runes option in svelte:options
The runes option forces a component into runes mode (runes={true}) or legacy mode (runes={false}).
namespace option in svelte:options
The namespace option specifies where the component will be used. Valid values are 'html' (the default), 'svg', or 'mathml'.
customElement option in svelte:options
The customElement option specifies options to use when compiling this component as a custom element. If a string is passed, it is used as the tag option. Example usage: <svelte:options customElement="my-custom-element" />
css="injected" option in svelte:options
The css="injected" option makes the component inject its styles inline. During server-side rendering, it is injected as a <style> tag in the head. During client-side rendering, it is loaded via JavaScript.
svelte:element with nullish this value does not render
If the this prop has a nullish value (null or undefined), the element and its children will not be rendered.
svelte:element only supports bind:this binding
The only supported binding for <svelte:element> is bind:this. Svelte's built-in bindings such as bind:value, bind:checked, and others do not work with generic elements created via <svelte:element>.
svelte:element renders dynamically named elements
The <svelte:element> element renders an element whose tag name is unknown at author time. The tag name is specified via the this={expression} prop. Any properties and event listeners present on the element will be applied to the rendered element.
svelte:element namespace can be specified with xmlns attribute
Svelte attempts to infer the correct namespace from the element's surroundings, but this is not always possible. You can make the namespace explicit by adding an xmlns attribute, such as xmlns="http://www.w3.org/2000/svg" for SVG elements.
svelte:element throws error for void elements with children in development
If this is the name of a void element such as 'br', 'hr', 'img', or 'input', and <svelte:element> has child elements, a runtime error will be thrown in development mode. Void elements cannot have child content.
svelte:element this prop must be a valid DOM element tag
The this prop must be a valid DOM element tag name. Invalid values like '#text' or 'svelte:head' will not work.
Special elements documentation section exists
Svelte 5 has a special elements documentation section that is auto-generated from apps/svelte.dev/scripts/sync-docs/index.ts.
Replace <svelte:component> with <DynamicComponent>
Use <DynamicComponent> instead of <svelte:component this={DynamicComponent}>.
Replace <svelte:self> with import and self-reference
Use import Self from './ThisComponent.svelte' and <Self> instead of <svelte:self>.
customElement replaces tag option in Svelte 4
The tag option in svelte:options is deprecated in favor of the new customElement option. Use <svelte:options customElement="my-component" /> instead of <svelte:options tag="my-component" />.
Content inside svelte:options is forbidden
In Svelte 5, content inside a <svelte:options /> tag is a compiler error. In Svelte 4 it was ignored.
Snippets replace slots in Svelte 5
In Svelte 5, snippets replace slots as the mechanism for passing content to components. They are more powerful and flexible than slots. Components using slots continue to work but snippets are the recommended approach.
children prop is passed by default to components
In Svelte 5, content inside component tags becomes a snippet prop called children. This replaces <slot /> from Svelte 4.
@render directive renders snippet content
Snippet content is rendered using {@render children()} syntax. The children prop is a function that returns the rendered snippet.
Multiple snippets use named props instead of named slots
In Svelte 5, instead of using named slots, you define multiple snippet props and render them with {@render header()}, {@render main()}, etc.
Snippets can receive parameters from parent components
Snippets can take parameters. The parent component calls the snippet with arguments: {#snippet item(text)} and the parent renders it with {@render item(entry)}
slot elements in declarative shadow roots are preserved
In Svelte 5, <slot /> tags inside <template shadowrootmode="..."> elements are preserved instead of being replaced with Svelte's slot implementation.
svelte:element this must be an expression
In Svelte 5, <svelte:element this="div"> is invalid. The this attribute must be an expression: <svelte:element this={"div">
dynamic_element_invalid_tag error
The <svelte:element this> prop must be a valid HTML element, SVG element, MathML element, or custom element name. Values containing invalid characters such as whitespace or special characters will not be rendered and could be a security risk.
Void elements cannot have content in svelte:element
Elements such as input, br, hr, img, and other void elements cannot have content. When using svelte:element with a void element tag, any children passed to that element will be ignored. This includes when the tag is specified dynamically with the 'this' attribute.
createAttachmentKey function purpose
createAttachmentKey creates an object key that will be recognised as an attachment when the object is spread onto an element. It serves as a programmatic alternative to using {@attach ...} tags. This is particularly useful for library authors, though generally not needed when building apps.
createAttachmentKey availability
createAttachmentKey has been available since Svelte 5.29.
createAttachmentKey return type
createAttachmentKey returns a symbol.
fromAction function purpose
fromAction converts an action into an attachment while keeping the same behavior. It is useful when you want to start using attachments on components but have actions provided by a library.
fromAction second argument requirement
When providing the second argument to fromAction, it must be a function that returns the argument to the action function, not the argument itself.
fromAction with parameter signature
fromAction can be called with an action and a function that returns the argument: fromAction<E extends EventTarget, T extends unknown>(action: Action<E, T> | ((element: E, arg: T) => void | ActionReturn<T>), fn: () => T): Attachment<E>
fromAction without parameter signature
fromAction can be called with just an action that takes no arguments: fromAction<E extends EventTarget>(action: Action<E, void> | ((element: E) => void | ActionReturn<void>)): Attachment<E>
Attachment definition
An Attachment is a function that runs when an element is mounted to the DOM and optionally returns a function that is called when the element is later removed. The signature is (element: T) => void | (() => void), where T extends EventTarget.
fromAction usage example
To convert an action to an attachment, use {@attach fromAction(foo, () => bar)} instead of use:foo={bar}. The second argument must be a function that returns the action argument.
Attachment attachment methods
An attachment can be attached to an element with an {@attach ...} tag, or by spreading an object containing a property created with createAttachmentKey.
createAttachmentKey usage example
To use createAttachmentKey, create a property in an object using [createAttachmentKey()] as the key, with a function as the value. When this object is spread onto an element with {...props}, the function will be called with the element as an argument.