From ae9972a91a86fbdcf05a42f676cbb1682f2175b5 Mon Sep 17 00:00:00 2001 From: Cory LaViska Date: Mon, 3 Apr 2023 16:19:35 -0500 Subject: [PATCH] clarify events; #1283 --- cspell.json | 1 + docs/getting-started/usage.md | 6 ++++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/cspell.json b/cspell.json index d3c5cd40..ebfc7a2a 100644 --- a/cspell.json +++ b/cspell.json @@ -111,6 +111,7 @@ "reregister", "resizer", "resizers", + "retargeted", "rgba", "roadmap", "Roboto", diff --git a/docs/getting-started/usage.md b/docs/getting-started/usage.md index adb47678..1b808f66 100644 --- a/docs/getting-started/usage.md +++ b/docs/getting-started/usage.md @@ -33,7 +33,9 @@ Refer to a component's documentation for a complete list of its properties. ## Events -You can listen for standard events such as `click`, `mouseover`, etc. as you normally would. In addition, some components emit custom events. These work the same way as standard events, but are prefixed with `sl-` to prevent collisions with standard events and other libraries. +You can listen for standard events such as `click`, `mouseover`, etc. as you normally would. However, it's important to note that many events emitted within a component's shadow root will be [retargeted](https://dom.spec.whatwg.org/#retarget) to the host element. This may result in, for example, multiple `click` handlers executing even if the user clicks just once. Furthermore, `event.target` will point to the host element, making things even more confusing. + +As a result, you should almost always listen for custom events instead. For example, instead of listening to `click` to determine when an `` gets toggled, listen to `sl-change`. ```html Check me @@ -46,7 +48,7 @@ You can listen for standard events such as `click`, `mouseover`, etc. as you nor ``` -Refer to a component's documentation for a complete list of its custom events. +All custom events are prefixed with `sl-` to prevent collisions with standard events and other libraries. Refer to a component's documentation for a complete list of its custom events. ## Methods