diff --git a/site/content/docs/02-template-syntax.md b/site/content/docs/02-template-syntax.md
index 0a4ca2ee1a..9112689ca0 100644
--- a/site/content/docs/02-template-syntax.md
+++ b/site/content/docs/02-template-syntax.md
@@ -979,6 +979,8 @@ Similar to `transition:`, but only applies to elements entering (`in:`) or leavi
 
 Unlike with `transition:`, transitions applied with `in:` and `out:` are not bidirectional — an in transition will continue to 'play' alongside the out transition, rather than reversing, if the block is outroed while the transition is in progress. If an out transition is aborted, transitions will restart from scratch.
 
+If an `out:` custom transition function returns a promise instead of a transition object, svelte will simply await its completion before unmounting the node.
+
 ```html
 {#if visible}
 	<div in:fly out:fade>
diff --git a/test/runtime/samples/transition-js-promise-outro/_config.js b/test/runtime/samples/transition-js-promise-outro/_config.js
new file mode 100644
index 0000000000..eba6971476
--- /dev/null
+++ b/test/runtime/samples/transition-js-promise-outro/_config.js
@@ -0,0 +1,14 @@
+export default {
+	props: {
+		visible: true,
+	},
+
+	test({ assert, component, target }) {
+		component.visible = false;
+		assert.notEqual(target.querySelector('span'), undefined);
+		component.resolve();
+		setTimeout(() => {
+			assert.equal(target.querySelector('span'), undefined);
+		});
+	},
+};
diff --git a/test/runtime/samples/transition-js-promise-outro/main.svelte b/test/runtime/samples/transition-js-promise-outro/main.svelte
new file mode 100644
index 0000000000..80b6cc6f2d
--- /dev/null
+++ b/test/runtime/samples/transition-js-promise-outro/main.svelte
@@ -0,0 +1,14 @@
+<script>
+	export let visible;
+	export let resolve
+
+	function foo(node, params) {
+		return new Promise(r => {
+			resolve = r
+		});
+	}
+</script>
+
+{#if visible}
+	<span out:foo>hello</span>
+{/if}