useSignal

State & data

A lightweight React hook for event-driven communication between components

Install

$ npm install @usefy/use-signal

Quick start

useSignal.tsx

import { useSignal } from "@usefy/use-signal";
import { useEffect } from "react";

// Emitter Component
function RefreshButton() {
  const { emit } = useSignal("dashboard-refresh");

  return <button onClick={emit}>Refresh Dashboard</button>;
}

// Subscriber Component
function DataWidget() {
  const { signal } = useSignal("dashboard-refresh");

  useEffect(() => {
    fetchData(); // Refetch when signal changes
  }, [signal]);

  return <div>Widget Content</div>;
}

API reference

`useSignal(name, options?)`

A hook that subscribes to a named signal and provides emit functionality.

Parameters

Parameter	Type	Description
`name`	`string`	Unique identifier for the signal
`options`	`SignalOptions`	Optional configuration (see below)

Options

interface SignalOptions {
  emitOnMount?: boolean; // Emit when component mounts (default: false)
  onEmit?: () => void; // Callback executed on emit
  enabled?: boolean; // Enable/disable subscription (default: true)
  debounce?: number; // Debounce emit calls in milliseconds
}

Returns `UseSignalReturn<T>`

Property	Type	Description
`signal`	`number`	Current version number (use in deps arrays)
`emit`	`(data?: T) => void`	Function to emit the signal with optional data
`info`	`SignalInfo<T>`	Metadata object (see below)

SignalInfo

interface SignalInfo<T = unknown> {
  readonly name: string; // Signal name
  readonly subscriberCount: number; // Active subscribers
  readonly timestamp: number; // Last emit timestamp
  readonly emitCount: number; // Total emit count
  readonly data: T | undefined; // Data passed with last emit
}

Note: info is a stable object whose fields are read-on-render snapshots, not reactive state. Reading a field (including info.subscriberCount) does not subscribe the component to changes in that value — it only reflects new data on renders that happen for another reason (e.g. after signal changes). In particular, info.subscriberCount will look stale if you bind it to UI (like a badge or button label) in a component that isn't itself re-rendering when other subscribers mount/unmount. Drive live UI from the signal version, and read the latest info.data inside a useEffect keyed on signal.

Go deeper

This page is the quick reference. For every example, prop, and edge case, read the full README — or open Storybook to change props live.

Full README →Open in Storybook →