signal

A collection of hooks that allow us to use signal features inside React components.

Independent package

These hooks are separate to an independent package @kaiverse/signal-react, and not included in this library anymore.

Version

Installation

No need to install the core package @kaiverse/signal separately.

pnpm

pnpm add @kaiverse/signal-react

npm

npm i @kaiverse/signal-react

Yarn

yarn add @kaiverse/signal-react

Hooks

import {
  useSignal,
  useSyncSignal,
  useSignalEffect,
  useComputed,
  useSyncComputed,
  useSignalValue,
  useSyncSignalValue,
} from '@kaiverse/signal-react'

Name	Description
useSignal/useSyncSignal	Creates a Signal that also happens to trigger React re-renders. You get both a Signal (usable in createEffect/createComputed) and React reactivity, same underlying value.
useSignalEffect	Runs an imperative effect whenever a Signal read inside it changes — the side-effect counterpart to the hooks below.
useComputed/useSyncComputed	Same as useSignal/useSyncSignal, but derived rather than a raw signal.
useSignalValue/useSyncSignalValue	Reads a Signal inside a React component. Returns a plain reactive value, that acts like React state, not a Signal.

useSignal

Create a Signal inside React component. It uses useReducer and returns a snapshot of Signal. It works better with concurrent rendering but has temporary tearing issue.

Consider using useSyncSignal which uses useSyncExternalStore that solves tearing issues, but doesn’t work well with concurrent rendering. It’s a trade-off, choose wisely.

Read more about the tearing issue.

useSyncSignal

Create a Signal inside React component. useSyncSignal is integrated with useSyncExternalStore (uSES) which is a recommended way to use “external stores” in React.

useSyncSignal works well in most cases. However, uSES doesn’t work with concurrent rendering. useSyncSignal’s setter wrapped with startTransition won’t behave as expected. Suspend a render based on a store value returned by uSES will trigger the nearest Suspense fallback instead of showing the old UI. Read more: useSyncExternalStore

useSignal, on the other hand, doesn’t use uSES. It returns a snapshot of Signal and uses useReducer to perform a re-render on Signal changes. As a result, It works better with concurrent rendering but suffers from temporary tearing issue.

It’s a trade-off after all. Choose the one that fits your use case.

useSignalEffect

Signal effect inside React component. It accepts an imperative function that will run whenever dependencies change. Dependencies are Signals that are used inside the Effect itself.

useSignalEffect can track either global Signal(s) or local (both inside or outside component) Signal(s) or all of them together.

use-signal-effect-example.tsx

import {createSignal, useSignalEffect} from '@kaiverse/signal-react'

const [count, setCount] = createSignal(0)

export function UseSignalEffectExample() {
  useSignalEffect(() => {
    console.log('count =', count()) // this will run whenever the increment button is clicked
  })

  return (
    <button type="button" onClick={() => setCount(count() + 1)}>
      Increment
    </button>
  )
}

useComputed

Derived signals inside React component.

Usually used to create a computed Signal from multiple useSignal, Signal(s) or to bind Signal(s), that created outside components, to React reactive system.

Only reacts to Signals

The factory only reacts to Signals read inside it — plain React state/props are invisible to it. Reading them is fine, but changes won’t trigger a recompute; the old value sticks around until some Signal change causes a recompute. To make a computed react to a React value, mirror it into a Signal first (e.g. useEffect(() => setSomeSignal(value), [value]))… But why?

Just reading one Signal, not deriving?

If factory only reads a single existing Signal without combining or transforming it (e.g. useComputed(() => globalCount())), prefer useSignalValue instead — it subscribes directly with no extra createComputed hop, so there’s no wrapping recompute and no owned resource to tear down on unmount.

React StrictMode (dev)

The double render pass creates a throwaway computed that is never cleaned up, so it stays subscribed to its dependencies. Harmless but real: every Signal it depends on recomputes for it on each change.

use-computed-example.tsx

import {useSignal, useComputed} from '@kaiverse/signal-react'
import {globalCountSignal} from './global-store'

const [globalCount, setGlobalCount] = globalCountSignal

export function UseComputedExample() {
  const [count, setCount] = useSignal(0)
  const sum = useComputed(() => count() + globalCount())

  return (
    <>
      <button type="button" onClick={() => setCount((c) => c + 1)}>
        count++
      </button>
      <button type="button" onClick={() => setGlobalCount(globalCount() + 2)}>
        Increase global count
      </button>
      Result: {count()} + {globalCount()} = {sum()}
    </>
  )
}

global-store.ts

import {createSignal} from '@kaiverse/signal-react'
export const globalCountSignal = createSignal(0)

The returned value is always the stable Signal getter. options.equals customizes the change comparison, same as createSignal.

useSyncComputed

Derived signals inside React component. useSyncComputed is integrated with useSyncExternalStore (uSES), the recommended way to use “external stores” in React, and solves the tearing issue.

The value returned is always the stable Signal getter. It shares useSyncSignal’s concurrent rendering caveats, since both are uSES-backed.

useComputed, on the other hand, uses useReducer and returns a snapshot of Signal. It works better with concurrent rendering but has the same temporary tearing issue as useSignal.

Just reading one Signal, not deriving?

Same as useComputed, if factory only reads a single existing Signal, prefer useSyncSignalValue instead. No extra createComputed hop, no owned resource to tear down.

React StrictMode (dev)

The double render pass creates a throwaway computed that is never cleaned up, so it stays subscribed to its dependencies. Harmless but real: every Signal it depends on recomputes for it on each change.

useSignalValue

Reads the current value of an already-existing Signal inside a React component.

Use this to consume a Signal created outside the component — a module-level store, or a Signal returned by another hook — as opposed to useSignal/useSyncSignal, which both create and own a Signal local to the component.

useSignalValue uses useReducer, same trade-off as useSignal: works better with concurrent rendering, has the temporary tearing issue. See useSyncSignalValue for the uSES-backed twin.

use-signal-value-example.tsx

import {useSignalValue} from '@kaiverse/signal-react'
import {globalCountSignal} from './global-store'

const [globalCount] = globalCountSignal

export function UseSignalValueExample() {
const count = useSignalValue(globalCount)
return <p>Global count: {count}</p>
}

global-store.ts

import {createSignal} from '@kaiverse/signal-react'
export const globalCountSignal = createSignal(0)

Returns a plain reactive value, not a Signal

useSignalValue/useSyncSignalValue return a plain reactive value, that acts like React state, not a Signal — it’s no longer trackable by useSignalEffect/useComputed. If you need tracking elsewhere, use the original Signal directly or useComputed/useSyncComputed instead.

const count = useSignalValue(globalCount) // count is a plain number state now

useSignalEffect(() => {
  console.log(count) // ❌ stale — never re-runs on its own
})

useSignalEffect(() => {
  console.log(globalCount()) // ✅ calls the original Signal — properly tracked
})

useEffect(() => {
  console.log(count) // ✅ rerun on globalCount signal value changes
}, [count])

Signal should be a stable reference

Expected to be a stable reference across renders — a module-level export, or one returned by another hook. Passing a fresh Signal created inline every render still works, but resubscribes on every render for no benefit; hoist it out instead.

useSyncSignalValue

Same as useSignalValue, but integrated with useSyncExternalStore instead of useReducer — same trade-off as useSyncSignal: solves the tearing issue, doesn’t work well with concurrent rendering.

use-sync-signal-value-example.tsx

import {useSyncSignalValue} from '@kaiverse/signal-react'
import {globalCountSignal} from './global-store'

const [globalCount] = globalCountSignal

export function UseSyncSignalValueExample() {
  const count = useSyncSignalValue(globalCount)
  return <p>Global count: {count}</p>
}

HMR

When a bundler hot-swaps a module that creates a Signal at module scope, the module re-evaluates and a new Signal instance is created: hooks created from it on first render stay subscribed to the dead instance, so the UI freezes and effects stop firing — while module-level effects are recreated on every save, duplicating on each edit.

Until a dedicated bundler plugin automates this, persist the Signal instance and dispose module-level effects yourself:

store.ts

import {createSignal, type SignalFactoryReturnType} from '@kaiverse/signal-react'

// Reuse the same Signal instance across HMR updates so one-time hook state
// (useComputed/useSignalValue/useSignalEffect) doesn't end up subscribed to a dead instance.
export const playgroundSignal =
  (import.meta.hot?.data.playgroundSignal as SignalFactoryReturnType<number>) ?? createSignal(0)

if (import.meta.hot) {
  import.meta.hot.data.playgroundSignal = playgroundSignal
  import.meta.hot.accept()
}

module with top-level effects

import {withHMR} from '@kaiverse/signal-react'

const {createEffect, createComputed} = withHMR(import.meta.hot)

createEffect(() => {
  console.log('globalCount =', globalCount())
})

A dedicated bundler plugin (@kaiverse/signal-plugins) that automates both is planned.