From b23839fb5f6943e94213026c6ae5e8e878edf3ac Mon Sep 17 00:00:00 2001
From: Richard Harris <richard.a.harris@gmail.com>
Date: Sun, 18 Aug 2019 19:55:35 -0400
Subject: [PATCH 1/2] add custom element documentation

---
 site/content/docs/03-run-time.md | 49 +++++++++++++++++++++++++++++++-
 1 file changed, 48 insertions(+), 1 deletion(-)

diff --git a/site/content/docs/03-run-time.md b/site/content/docs/03-run-time.md
index 193e880ea6..656ee147a4 100644
--- a/site/content/docs/03-run-time.md
+++ b/site/content/docs/03-run-time.md
@@ -907,7 +907,54 @@ app.count += 1;
 
 ### Custom element API
 
-* TODO
+---
+
+Svelte components can also be compiled to custom elements (aka web components) using the `customElements: true` compiler option. You should specify a tag name for the component using the [`<svelte:options>`](docs#svelte_options) element.
+
+```html
+<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.
+
+```js
+import MyElement from './MyElement.svelte';
+
+customElements.define('my-element', MyElement);
+```
+
+---
+
+By default, custom elements are compiled with `accessors: true`, which means that any [props](docs#Attributes_and_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>`.
+
+```js
+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](https://custom-elements-everywhere.com/). 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
+* Polyfills are required to support older browsers
+
 
 
 ### Server-side component API

From de24efd3b86a16433c1ff4c986f061ac0985bd89 Mon Sep 17 00:00:00 2001
From: Richard Harris <richard.a.harris@gmail.com>
Date: Sun, 18 Aug 2019 20:08:17 -0400
Subject: [PATCH 2/2] small fix

---
 site/content/docs/03-run-time.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/site/content/docs/03-run-time.md b/site/content/docs/03-run-time.md
index 656ee147a4..b06911a4de 100644
--- a/site/content/docs/03-run-time.md
+++ b/site/content/docs/03-run-time.md
@@ -909,7 +909,7 @@ app.count += 1;
 
 ---
 
-Svelte components can also be compiled to custom elements (aka web components) using the `customElements: true` compiler option. You should specify a tag name for the component using the [`<svelte:options>`](docs#svelte_options) element.
+Svelte components can also be compiled to custom elements (aka web components) using the `customElements: true` compiler option. You should specify a tag name for the component using the `<svelte:options>` [element](docs#svelte_options).
 
 ```html
 <svelte:options tag="my-element">