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