Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: fix syntax error and improve docs in use-event-listener.md #136

Merged
merged 6 commits into from
Sep 29, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 34 additions & 9 deletions sites/docs/content/utilities/use-event-listener.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,35 +14,60 @@ 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 `<svelte:body />`, 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 `<svelte:body />`, 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
<script lang="ts">
import { ClickLogger } from "./ClickLogger.ts";

const logger = new ClickLogger();
</script>

<p>You've clicked the document {logger.clicks} {logger.clicks === 1 ? "time" : "times"}</p>
<p>
You've clicked the document {logger.clicks}
{logger.clicks === 1 ? "time" : "times"}
</p>
```

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.