![\"usefy](\"https://raw.githubusercontent.com/mirunamu00/usefy/master/assets/logo.png\"){kind=logo}
\n\n \n
\n A lightweight React hook for event-driven communication between components\n
\n\n\n \n ![\"npm](\"https://img.shields.io/npm/v/@usefy/use-signal.svg?style=flat-square&color=007acc\")
\n \n \n ![\"npm](\"https://img.shields.io/npm/dm/@usefy/use-signal.svg?style=flat-square&color=007acc\")
\n \n \n ![\"bundle](\"https://img.shields.io/bundlephobia/minzip/@usefy/use-signal?style=flat-square&color=007acc\")
![\"license\"](\"https://img.shields.io/npm/l/@usefy/use-signal.svg?style=flat-square&color=007acc\")
\n \n
\n Installation β’\n Quick Start β’\n API Reference β’\n Examples β’\n License\n
\n\n\n \n π View Storybook Demo\n \n
\n\n---\n\n## Overview\n\n`@usefy/use-signal` enables event-driven communication between React components without prop drilling or complex state management setup. Components subscribe to a shared \"signal\" by name, and when any component emits that signal, all subscribers receive an update.\n\n**Part of the [@usefy](https://www.npmjs.com/org/usefy) ecosystem** β a collection of production-ready React hooks designed for modern applications.\n\n### Why use-signal?\n\n- **Zero Dependencies** β Pure React implementation with no external dependencies\n- **TypeScript First** β Full type safety with exported interfaces\n- **Stable References** β `emit` and `info` maintain stable references across re-renders\n- **SSR Compatible** β Works seamlessly with Next.js, Remix, and other SSR frameworks\n- **Lightweight** β Minimal bundle footprint (~1KB minified + gzipped)\n- **Well Tested** β Comprehensive test coverage with Vitest\n- **React 18+ Optimized** β Uses `useSyncExternalStore` for concurrent mode compatibility\n\n### Use Cases\n\n- **Dashboard Refresh** β Refresh multiple widgets with a single button click\n- **Form Reset** β Reset multiple form sections simultaneously\n- **Cache Invalidation** β Invalidate and reload data across components\n- **Multi-step Flows** β Coordinate state across wizard steps\n- **Event Broadcasting** β Notify multiple listeners about system events\n\n### β οΈ What This Hook Is NOT\n\n**`useSignal` is NOT a global state management solution.**\n\nThis hook is designed for lightweight event-driven communicationβsharing simple \"signals\" between components without the overhead of complex state management setup.\n\nIf you need:\n- Complex shared state with derived values\n- Persistent state across page navigation\n- State that drives business logic\n- Fine-grained state updates with selectors\n\nβ Use dedicated state management tools like **React Context**, **Zustand**, **Jotai**, **Recoil**, or **Redux**.\n\n**About `info.data`:** The data payload feature exists for cases where you need to pass contextual information along with a signal (e.g., which item was clicked, what action was performed). It's meant for event metadata, not as a global state container.\n\n```tsx\n// β Good: Signal with contextual data\nemit({ itemId: \"123\", action: \"refresh\" });\n\n// β Bad: Using as global state\nemit({ user: userData, cart: cartItems, settings: appSettings });\n```\n\n---\n\n## Installation\n\n```bash\n# npm\nnpm install @usefy/use-signal\n\n# yarn\nyarn add @usefy/use-signal\n\n# pnpm\npnpm add @usefy/use-signal\n```\n\n### Peer Dependencies\n\nThis package requires React 18 or 19:\n\n```json\n{\n \"peerDependencies\": {\n \"react\": \"^18.0.0 || ^19.0.0\"\n }\n}\n```\n\n---\n\n## Quick Start\n\n```tsx\nimport { useSignal } from \"@usefy/use-signal\";\nimport { useEffect } from \"react\";\n\n// Emitter Component\nfunction RefreshButton() {\n const { emit } = useSignal(\"dashboard-refresh\");\n\n return ;\n}\n\n// Subscriber Component\nfunction DataWidget() {\n const { signal } = useSignal(\"dashboard-refresh\");\n\n useEffect(() => {\n fetchData(); // Refetch when signal changes\n }, [signal]);\n\n return\n Built with care by the usefy team\n
\n","readmeFilename":"README.md"}