React

Signals are framework-agnostic — they work the same whether you’re in a custom element, a vanilla script, or a React tree. These two hooks connect them to React’s rendering model via useSyncExternalStore, so React only re-renders components that actually depend on a changed signal.

// integrations/react is included with elements-kit — no extra install needed
import { useSignal, useScope } from "elements-kit/integrations/react";

useSignal

Subscribe a React component to any signal or computed value. Returns the current value and re-renders the component whenever it changes.

/** @jsxImportSource react */
import { 
function signal<T>(): Updater<T> & Computed<T> (+1 overload)
Creates a mutable reactive signal.

Read: call with no arguments → returns the current value and
subscribes the active tracking context.
Write: call with a value → updates the signal and schedules
downstream effects if the value changed.
@example 
const count = signal(0);
count();        // → 0  (read)
count(1);       // write – effects depending on count will re-run
count();        // → 1
signal, 
function computed<T>(getter: (previousValue?: T) => T): () => T
Creates a lazily-evaluated computed value.
The getter is only called when the computed value is read and one of
its dependencies has changed since the last evaluation.  If nothing has
changed the cached value is returned without re-running getter.
Computed values are read-only; they cannot be set directly.
@param ― getter - Pure function deriving a value from other reactive sources.
Receives the previous value as an optional optimisation hint.
@example 
const a = signal(1);
const b = signal(2);
const sum = computed(() => a() + b());

sum(); // → 3
a(10);
sum(); // → 12  (re-evaluated lazily)
computed } from "elements-kit/signals";
import { 
function useSignal<T>(value: () => T, getServerSnapshot?: () => T): T
Subscribe to any readable signal — writable or computed — returning its current value.
Accepts any zero-argument callable () => T, which includes both Signal<T> and
Computed<T>. Using () => T instead of Computed<T> prevents TypeScript from
picking the write overload of Signal<T> during type inference.
Server rendering: pass getServerSnapshot for any component React renders
on the server — React requires it there and throws without one. It runs on
the server and again for the hydration render on the client, so it must
return the same value both times: whatever the server put in the HTML. A
signal reading browser state (matchMedia, localStorage, location) does
not qualify, since it answers differently in the browser.
@template ― T - The type of the signal value.
@param ― value - A writable Signal<T> or a derived Computed<T>.
@param ― getServerSnapshot - Returns the value the server rendered. Required
for server-rendered components; omit only for client-only ones.
@returns ― The current value, updated on every signal change.
@example 
const count = signal(0);
const double = computed(() => count() * 2);

function Display() {
  const countValue = useSignal(count);
  const doubleValue = useSignal(double);
  return <div>{countValue} × 2 = {doubleValue}</div>;
}
@example 
Server-rendered component reading a browser-only signal:
// `theme` resolves to "light" on the server — say so, or hydration mismatches.
const mode = useSignal(theme, () => "light");
useSignal } from "elements-kit/integrations/react";

// Defined outside any component — shared reactive state
const 
const theme: Updater<"light" | "dark"> & Computed<"light" | "dark">
theme = 
signal<"light" | "dark">(initialValue: "light" | "dark"): Updater<"light" | "dark"> & Computed<"light" | "dark"> (+1 overload)
Creates a mutable reactive signal.

Read: call with no arguments → returns the current value and
subscribes the active tracking context.
Write: call with a value → updates the signal and schedules
downstream effects if the value changed.
@example 
const count = signal(0);
count();        // → 0  (read)
count(1);       // write – effects depending on count will re-run
count();        // → 1
signal<"light" | "dark">("light");
const 
const isDark: () => boolean
isDark = 
computed<boolean>(getter: (previousValue?: boolean | undefined) => boolean): () => boolean
Creates a lazily-evaluated computed value.
The getter is only called when the computed value is read and one of
its dependencies has changed since the last evaluation.  If nothing has
changed the cached value is returned without re-running getter.
Computed values are read-only; they cannot be set directly.
@param ― getter - Pure function deriving a value from other reactive sources.
Receives the previous value as an optional optimisation hint.
@example 
const a = signal(1);
const b = signal(2);
const sum = computed(() => a() + b());

sum(); // → 3
a(10);
sum(); // → 12  (re-evaluated lazily)
computed(() => 
const theme: () => "light" | "dark" (+1 overload)
theme() === "dark");

function 
function ThemeToggle(): JSX.Element
ThemeToggle() {
  const 
const dark: boolean
dark = 
useSignal<boolean>(value: () => boolean, getServerSnapshot?: (() => boolean) | undefined): boolean
Subscribe to any readable signal — writable or computed — returning its current value.
Accepts any zero-argument callable () => T, which includes both Signal<T> and
Computed<T>. Using () => T instead of Computed<T> prevents TypeScript from
picking the write overload of Signal<T> during type inference.
Server rendering: pass getServerSnapshot for any component React renders
on the server — React requires it there and throws without one. It runs on
the server and again for the hydration render on the client, so it must
return the same value both times: whatever the server put in the HTML. A
signal reading browser state (matchMedia, localStorage, location) does
not qualify, since it answers differently in the browser.
@template ― T - The type of the signal value.
@param ― value - A writable Signal<T> or a derived Computed<T>.
@param ― getServerSnapshot - Returns the value the server rendered. Required
for server-rendered components; omit only for client-only ones.
@returns ― The current value, updated on every signal change.
@example 
const count = signal(0);
const double = computed(() => count() * 2);

function Display() {
  const countValue = useSignal(count);
  const doubleValue = useSignal(double);
  return <div>{countValue} × 2 = {doubleValue}</div>;
}
@example 
Server-rendered component reading a browser-only signal:
// `theme` resolves to "light" on the server — say so, or hydration mismatches.
const mode = useSignal(theme, () => "light");
useSignal(
const isDark: () => boolean
isDark);

  return (
    <
React.JSX.IntrinsicElements.button: React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>
button 
React.DOMAttributes<HTMLButtonElement>.onClick?: React.MouseEventHandler<HTMLButtonElement> | undefined
onClick={() => 
const theme: (value: "light" | "dark") => void (+1 overload)
theme(
const dark: boolean
dark ? "light" : "dark")}>
      Switch to {
const dark: boolean
dark ? "light" : "dark"} mode
    </
React.JSX.IntrinsicElements.button: React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>
button>
  );
}

How it works

useSignal wraps useSyncExternalStore. It creates a signal effect that reads the value and calls React’s onStoreChange callback whenever the signal updates. This is concurrent-mode safe — React can interrupt renders without missing updates.

// Accepts any () => T — both Signal<T> and Computed<T>
useSignal(count)          // Signal<number>
useSignal(doubled)        // Computed<number>
useSignal(() => items().length) // inline expression

Components only re-render when their signal dependencies change — not on every signal write in the app.

Server rendering

React calls getServerSnapshot on the server, and again in the browser for the hydration render. Both runs must return the same thing — whatever the server put in the HTML — so it cannot read browser state.

// `theme` is "light" on the server: no matchMedia, no localStorage.
const mode = useSignal(theme, () => "light");

Immediately after hydration React re-reads the live value and re-renders, so a dark-mode user ends up on "dark"; the first paint is what the server sent.

It is required for any component React renders on the server. Omit it there and React throws:

Missing getServerSnapshot, which is required for server-rendered content.

Omit it only for client-only components — an Astro island marked client:only, for instance — where the server snapshot is never called.

Passing the live signal is the common mistake, and it type-checks:

useSignal(theme, () => theme()); // ✗ reads the browser during hydration
useSignal(theme, () => "light"); // ✓ a value the server committed to

useScope

Creates a signal effect scope tied to the component’s lifetime. All effects registered inside the callback are stopped automatically when the component unmounts.

If the callback returns a Computed<T>, useScope subscribes to it and returns the current value — like useSignal but with its own scope for side effects.

StrictMode-safe. The scope is held in a ref, so React’s development-mode double mount/unmount reuses the same scope — no duplicate effects, no leaked subscriptions.

import { effect, onCleanup } from "elements-kit/signals";
import { useScope } from "elements-kit/integrations/react";

function Logger() {
  useScope(() => {
    // All effects here are cleaned up on unmount
    effect(() => console.log("count:", count()));
    effect(() => console.log("user:", user()));

    // onCleanup composes naturally inside the scope
    effect(() => {
      const ws = new WebSocket(endpoint());
      onCleanup(() => ws.close());
    });
  });

  return null;
}

Returning a computed value

import { computed } from "elements-kit/signals";
import { useScope } from "elements-kit/integrations/react";

function ExpensiveMetrics() {
  // Compute inside the scope — lifecycle managed by the component
  const metrics = useScope(() =>
    computed(() => ({
      total: items().reduce((s, i) => s + i.value, 0),
      count: items().length,
    }))
  );

  return (
    <dl>
      <dt>Total</dt><dd>{metrics?.total}</dd>
      <dt>Count</dt><dd>{metrics?.count}</dd>
    </dl>
  );
}

When to use each hook

	`useSignal`	`useScope`
Read a signal / computed	✓	✓ (return computed)
Run side effects	—	✓
Group multiple effects	—	✓
Cleanup on unmount	automatic	automatic
StrictMode-safe	✓	✓

Store

A store is a plain class with @reactive fields — framework-agnostic reactive state. Reading from a store inside useSignal or useScope creates a live subscription exactly like reading a signal directly.

import { 
function reactive<This extends object, Value>(source?: (self: This) => Signal<Value>): (_target: unknown, context: ClassFieldDecoratorContext<This, Value>) => (this: This, initialValue: Value) => Value
A decorator that makes a class field reactive by automatically wrapping its value in a signal.
The field behaves like a normal property (get/set) but reactivity is tracked under the hood.
Any reads will subscribe to the signal and any writes will trigger updates.
@example 
class Counter {
  \@reactive() count: number = 0;
}

const counter = new Counter();
counter.count++;        // Triggers reactivity
console.log(counter.count); // Subscribes to changes
@remarks ― 
Equivalent to manually creating a private signal and getter/setter:
class Counter {
  #count = signal(0);
  get count() { return this.#count(); }
  set count(value) { this.#count(value); }
}
reactive, 
function computed<T>(getter: (previousValue?: T) => T): () => T
Creates a lazily-evaluated computed value.
The getter is only called when the computed value is read and one of
its dependencies has changed since the last evaluation.  If nothing has
changed the cached value is returned without re-running getter.
Computed values are read-only; they cannot be set directly.
@param ― getter - Pure function deriving a value from other reactive sources.
Receives the previous value as an optional optimisation hint.
@example 
const a = signal(1);
const b = signal(2);
const sum = computed(() => a() + b());

sum(); // → 3
a(10);
sum(); // → 12  (re-evaluated lazily)
computed } from "elements-kit/signals";

export class 
class CounterStore
CounterStore {
  @
reactive<object, unknown>(source?: ((self: object) => Signal<unknown>) | undefined): (_target: unknown, context: ClassFieldDecoratorContext<object, unknown>) => (this: object, initialValue: unknown) => unknown
A decorator that makes a class field reactive by automatically wrapping its value in a signal.
The field behaves like a normal property (get/set) but reactivity is tracked under the hood.
Any reads will subscribe to the signal and any writes will trigger updates.
@example 
class Counter {
  \@reactive() count: number = 0;
}

const counter = new Counter();
counter.count++;        // Triggers reactivity
console.log(counter.count); // Subscribes to changes
@remarks ― 
Equivalent to manually creating a private signal and getter/setter:
class Counter {
  #count = signal(0);
  get count() { return this.#count(); }
  set count(value) { this.#count(value); }
}
reactive() 
CounterStore.count: number
count = 0;
  
CounterStore.doubled: () => number
doubled = 
computed<number>(getter: (previousValue?: number | undefined) => number): () => number
Creates a lazily-evaluated computed value.
The getter is only called when the computed value is read and one of
its dependencies has changed since the last evaluation.  If nothing has
changed the cached value is returned without re-running getter.
Computed values are read-only; they cannot be set directly.
@param ― getter - Pure function deriving a value from other reactive sources.
Receives the previous value as an optional optimisation hint.
@example 
const a = signal(1);
const b = signal(2);
const sum = computed(() => a() + b());

sum(); // → 3
a(10);
sum(); // → 12  (re-evaluated lazily)
computed(() => this.
CounterStore.count: number
count * 2);

  
CounterStore.increment(): void
increment() { this.
CounterStore.count: number
count++; }
  
CounterStore.decrement(): void
decrement() { this.
CounterStore.count: number
count--; }
  
CounterStore.reset(): void
reset()     { this.
CounterStore.count: number
count = 0; }
}

// Singleton shared across the whole app — or per-tree instances
export const 
const counter: CounterStore
counter = new 
constructor CounterStore(): CounterStore
CounterStore();

import { useSignal } from "elements-kit/integrations/react";
import { counter } from "./store";

export function Counter() {
  // () => store.field — the getter reads the signal, creating a subscription
  const count = useSignal(() => counter.count);
  const doubled = useSignal(counter.doubled); // Computed<T> works directly

  return (
    <div>
      <p>{count} × 2 = {doubled}</p>
      <button onClick={() => counter.increment()}>+1</button>{" "}
      <button onClick={() => counter.decrement()}>−1</button>{" "}
      <button onClick={() => counter.reset()}>Reset</button>
    </div>
  );
}

The store doesn’t know about React. The same counter instance can drive a custom element, a React component, and a plain effect — all sharing the same reactive state and updating in sync.

Custom elements in JSX

A custom element built with elements-kit is just class extends HTMLElement registered via customElements.define. React renders it fine at runtime, but React’s JSX.IntrinsicElements is independent of elements-kit’s, so you need a small augmentation to get typed props, narrowed ref, and editor autocomplete on the React side.

Source the prop shape from the class

Three type helpers exported from elements-kit/custom-elements read the raw platform surface off the class. All three take the constructor (typeof XCounter); PropertiesOf also accepts an instance type.

Helper	Shape	Use when
`PropertiesOf<typeof XCounter>`	Public instance fields, all optional — the `HTMLElement` surface is dropped; `Slot`-typed fields accept a `Node`	Typing property assignments — prop bindings, wrappers, helper functions
`AttributesOf<typeof XCounter>`	Every key of `static [ATTRIBUTES]`, valued `string \| null`	Typing the raw HTML attribute surface — `setAttribute`, server-rendered markup
`EventsOf<typeof XCounter>`	The `static events` map, verbatim — event name to event type	Typing `addEventListener`, framework event bindings, `HTMLElementEventMap` augmentations

For most React wiring PropertiesOf<typeof XCounter> is enough.

Augment React’s `JSX.IntrinsicElements`

import type { PropertiesOf } from "elements-kit/custom-elements";
import type { XCounter } from "./x-counter";

declare module "react" {
  namespace JSX {
    interface IntrinsicElements {
      "x-counter": React.DetailedHTMLProps<
        React.HTMLAttributes<XCounter> & PropertiesOf<typeof XCounter>,
        XCounter
      >;
    }
  }
}

// <x-counter count={5} ref={(el) => …} />  — el: XCounter

React.DetailedHTMLProps is what gives you the standard HTML attribute surface (className, id, onClick, …) and a ref narrowed to XCounter.

Co-locate the augmentation with the class

Put the declare module "react" block in the same file as the element class. Importing the class then brings the augmentation along — consumers don’t have to remember to write it themselves.

import { defineElement, type PropertiesOf } from "elements-kit/custom-elements";
import { reactive } from "elements-kit/signals";

export class XCounter extends HTMLElement {
  @reactive() count = 0;
}

defineElement("x-counter", XCounter);

declare module "react" {
  namespace JSX {
    interface IntrinsicElements {
      "x-counter": React.DetailedHTMLProps<
        React.HTMLAttributes<XCounter> & PropertiesOf<typeof XCounter>,
        XCounter
      >;
    }
  }
}

Typed `document.querySelector` and `createElement`

Independent of any JSX framework, augmenting the global HTMLElementTagNameMap gives you typed lookups in plain DOM code:

declare global {
  interface HTMLElementTagNameMap {
    "x-counter": XCounter;
  }
}

const el = document.querySelector("x-counter"); // XCounter | null

Worth doing alongside the React augmentation.