From ce047651e50c9a14a22fe0bcf42f4da52f31f517 Mon Sep 17 00:00:00 2001
From: Ben McCann <322311+benmccann@users.noreply.github.com>
Date: Fri, 28 Jul 2023 03:11:14 -0700
Subject: [PATCH] docs: update component directives page (#9040)

---
 .../06-component-directives.md                | 31 ++++++++++++++++---
 1 file changed, 27 insertions(+), 4 deletions(-)

diff --git a/documentation/docs/02-template-syntax/06-component-directives.md b/documentation/docs/02-template-syntax/06-component-directives.md
index b072074a59..f1d49323bd 100644
--- a/documentation/docs/02-template-syntax/06-component-directives.md
+++ b/documentation/docs/02-template-syntax/06-component-directives.md
@@ -8,13 +8,34 @@ title: Component directives
 on:eventname={handler}
 ```
 
-Components can emit events using [createEventDispatcher](/docs/svelte#createeventdispatcher), or by forwarding DOM events. Listening for component events looks the same as listening for DOM events:
+Components can emit events using [`createEventDispatcher`](/docs/svelte#createeventdispatcher) or by forwarding DOM events.
+
+```svelte
+<!-- SomeComponent.svelte -->
+<script>
+  import { createEventDispatcher } from 'svelte';
+
+  const dispatch = createEventDispatcher();
+</script>
+
+<!-- programmatic dispatching -->
+<button on:click={() => dispatch('hello')}>
+  one
+</button>
+
+<!-- declarative event forwarding -->
+<button on:click>
+  two
+</button>
+```
+
+Listening for component events looks the same as listening for DOM events:
 
 ```svelte
 <SomeComponent on:whatever={handler} />
 ```
 
-As with DOM events, if the `on:` directive is used without a value, the component will _forward_ the event, meaning that a consumer of the component can listen for it.
+As with DOM events, if the `on:` directive is used without a value, the event will be forwarded, meaning that a consumer can listen for it.
 
 ```svelte
 <SomeComponent on:whatever />
@@ -92,6 +113,8 @@ You can bind to component props using the same syntax as for elements.
 <Keypad bind:value={pin} />
 ```
 
+While Svelte props are reactive without binding, that reactivity only flows downward into the component by default. Using `bind:property` allows changes to the property from within the component to flow back up out of the component.
+
 ## bind:this
 
 ```svelte
@@ -100,10 +123,10 @@ bind:this={component_instance}
 
 Components also support `bind:this`, allowing you to interact with component instances programmatically.
 
-> Note that we can't do `{cart.empty}` since `cart` is `undefined` when the button is first rendered and throws an error.
-
 ```svelte
 <ShoppingCart bind:this={cart} />
 
 <button on:click={() => cart.empty()}> Empty shopping cart </button>
 ```
+
+> Note that we can't do `{cart.empty}` since `cart` is `undefined` when the button is first rendered and throws an error.