diff --git a/sites/docs/content/utilities/use-event-listener.md b/sites/docs/content/utilities/use-event-listener.md index ca5f89ce..5019b9e7 100644 --- a/sites/docs/content/utilities/use-event-listener.md +++ b/sites/docs/content/utilities/use-event-listener.md @@ -14,29 +14,39 @@ import Demo from '$lib/components/demos/use-event-listener.svelte'; ## Usage -This is better utilized in elements that you don't have direct control over. Otherwise, use normal -event listeners. +The `useEventListener` function is particularly useful for attaching event listeners to elements you +don't directly control. For instance, if you need to listen for events on the document body or +window and can't use ``, or if you receive an element reference from a parent +component. -For example, if you want to listen to a click event on the body, and can't use ``, or -you have an element reference that was passed down. +### Example: Tracking Clicks on the Document ```ts // ClickLogger.ts import { useEventListener } from "runed"; -export class ClickLogger() { - #clicks = $state(0) +export class ClickLogger { + #clicks = $state(0); constructor() { - useEventListener(() => document.body, "click", () => this.#clicks++); + useEventListener( + () => document.body, + "click", + () => this.#clicks++ + ); } get clicks() { - return this.#clicks + return this.#clicks; } } ``` +This `ClickLogger` class tracks the number of clicks on the document body using the +`useEventListener` function. Each time a click occurs, the internal counter increments. + +### Svelte Component Usage + ```svelte -

You've clicked the document {logger.clicks} {logger.clicks === 1 ? "time" : "times"}

+

+ You've clicked the document {logger.clicks} + {logger.clicks === 1 ? "time" : "times"} +

``` + +In the component above, we create an instance of the `ClickLogger` class to monitor clicks on the +document. The displayed text updates dynamically based on the recorded click count. + +### Key Points + +- **Automatic Cleanup:** The event listener is removed automatically when the component is destroyed + or when the element reference changes. +- **Lazy Initialization:** The target element can be defined using a function, enabling flexible and + dynamic behavior. +- **Convenient for Global Listeners:** Ideal for scenarios where attaching event listeners directly + to the DOM elements is cumbersome or impractical.