1.0.3 • Published 10 months ago

@stainless-code/react-custom-events v1.0.3

Weekly downloads
-
License
MIT
Repository
github
Last release
10 months ago

@stainless-code/react-custom-events

This library provides utilities to simplify working with custom DOM events in React, allowing you to dispatch and listen for events in a declarative and type-safe manner.

Features

  • Typesafe
  • Reusable
  • Simple API
  • Centralised event dispatcher and listener

Installation

npm

npm install @stainless-code/react-custom-events

yarn

yarn add @stainless-code/react-custom-events

pnpm

pnpm add @stainless-code/react-custom-events

bun

bun add @stainless-code/react-custom-events

Usage

1. Basic

import { createCustomEvent } from "@stainless-code/react-custom-events";

// Create event
const useMyEvent = createCustomEvent<string>("my-event");

function MyComponent() {
  // Listen for the event
  useMyEvent((payload) => console.log("Event received with payload:", payload));

  return (
    // Dispatch event
    <button onClick={() => useMyEvent.dispatch("hello!")}>
      Dispatch event
    </button>
  );
}

2. With options and dependency list

import { createCustomEvent } from "@stainless-code/react-custom-events";
import { useState } from "react";

// Create event
const useMyEvent = createCustomEvent<string>("my-event");

function MyComponent() {
  const [enabled, setEnabled] = useState(true);

  // Listen for the event
  useMyEvent(
    (payload, event) =>
      console.log("Event received with payload:", payload, event),
    {
      listen: enabled, // Control whether the listener is active
      onStartListening: () => console.log("Started listening"),
      onStopListening: () => console.log("Stopped listening"),
    },
    [enabled], // Re-subscribe when `enabled` changes
  );

  return (
    <>
      <button onClick={() => setEnabled(!enabled)}>
        {enabled ? "Disable" : "Enable"} event listener
      </button>
      <button onClick={() => useMyEvent.dispatch("hello!")}>
        Dispatch event
      </button>
    </>
  );
}

Typesafety

const useMyEvent = createCustomEvent<string>("my-event");

// dispatching
useMyEvent.dispatch("Valid string payload"); // ✅ Correct type
useMyEvent.dispatch(123); // ❌ TypeScript error: Expected 'string', got 'number'

// listening
useMyEvent((payload) => {
  console.log(payload.toUpperCase()); // ✅ Correct method for string
  console.log(payload * 2); // ❌ TypeScript error: 'string' is not a number
});

API

createCustomEvent()

Creates a custom event with a given name and returns a hook for listening to it and a dispatch function for triggering the event.

ParameterTypeDescriptionDefault
eventNamestringThe name of the custom event.(required)

Returns

  • useCustomEventListener with eventName prepopulated along with a dispatch method to trigger the event and the eventName property.

useCustomEventListener()

Custom hook to listen for a custom event and handle the payload.

ParameterTypeDescriptionDefault
eventNamestringThe name of the custom event to listen for.(required)
onListen(payload: Payload, event: CustomEvent<Payload>) => voidCallback to handle the event payload and event object.(required)
options (optional)ObjectAdditional configuration for the event listener.{ listen: true }
options.listenbooleanWhether the listener should be active (default: true).true
options.onStartListening() => voidCallback when the listener starts.undefined
options.onStopListening() => voidCallback when the listener stops.undefined
deps (optional)DependencyListDependency list for re-subscribing to the event.undefined

Contributing

Feel free to submit issues or PRs to improve the library!

License

MIT

1.0.3

10 months ago

1.0.2

10 months ago

1.0.1

10 months ago

1.0.0

10 months ago