Signals

Signals are the reactive core of ElementsKit. Every UI update, derived value, and side effect is driven by three primitives: signal, computed, and effect.

Counter

Batch

onCleanup

effectScope

untracked

signal

A signal holds a single reactive value. Call it with no arguments to read, with an argument to write.

Prev

1 / 4

Next

import { signal } from "elements-kit/signals";

const name = signal("Alice");
const name: Updater<string> & Computed<string>
name();          // "Alice"
name("Bob");     // write
name();          // "Bob"

Signals are synchronous — every write immediately notifies dependents.

Reactive children need () =>

In JSX, signal/computed values must be wrapped in a function:

// ❌ Wrong — reads once, never updates
<p>{count()}</p>

// ✅ Correct — reads on every change
<p>{() => count()}</p>

computed

A computed derives a value from one or more signals. It is lazy — only re-evaluates when a dependency has changed and the value is read again. Results are cached between reads.

Prev

1 / 3

Next

import { signal, computed } from "elements-kit/signals";

const firstName = signal("Ada");
const lastName  = signal("Lovelace");

const fullName = computed(() => `${firstName()} ${lastName()}`);
const fullName: () => string
fullName(); // "Ada Lovelace"

firstName("Grace");
fullName(); // "Grace Lovelace"

A computed is read-only — you can only call it with no arguments.

---

effect

An effect runs a side effect whenever its signal dependencies change. It runs immediately on creation to collect dependencies, then re-runs on every change. Returns a stop function.

Prev

1 / 4

Next

import { signal, effect } from "elements-kit/signals";

const theme = signal("light");

const stop = effect(() => {
const stop: () => void
  // Reads theme — becomes a dependency automatically
  document.body.dataset.theme = theme();
});

theme("dark"); // body.dataset.theme = "dark"

stop();        // Unsubscribe — no more updates

Effects track dependencies dynamically — only the signals actually read during the last run are tracked.

Reading signals outside effects

Signals only trigger updates when read inside a reactive context (effect, computed, or reactive JSX). Reading outside gives you the current value but won’t re-run:

const name = signal("Alice");

// Logs once — not reactive
console.log(name());

// Re-runs whenever name changes
effect(() => console.log(name()));

effectScope

Groups multiple effects under a single lifecycle. Calling the returned stop function disposes all effects at once.

import { signal, effect, effectScope } from "elements-kit/signals";

const user  = signal("Alice");
const page  = signal("/home");

// All effects inside are grouped together
const stop = effectScope(() => {
const stop: () => void
  effect(() => console.log("user:", user()));
  effect(() => console.log("page:", page()));
});

user("Bob");   // → user: Bob
page("/about"); // → page: /about

stop(); // Both effects disposed — silence

Use effectScope when you want to start and stop a group of related effects together — e.g. tied to a component’s lifetime.

JSX already scopes for you

Function components, intrinsic elements, fragments, and <For> items each create their own effectScope. You only need to create one by hand in custom-element lifecycle hooks or other non-JSX entry points — see Scopes & cleanup.

---

onCleanup

Registers a cleanup callback inside the currently running effect or effectScope. The callback runs before the effect re-runs and when the effect is disposed.

import { signal, effect, onCleanup } from "elements-kit/signals";

const url = signal("/api/data");

effect(() => {
  const controller = new AbortController();

  fetch(url(), { signal: controller.signal })
    .then((r) => r.json())
    .then(console.log);

  // Runs before the next fetch (url changed) or on stop()
  onCleanup(() => controller.abort());
});

url("/api/other"); // previous fetch aborted, new one starts

onCleanup works at any call depth inside the effect — you can call it anywhere without passing anything down.

You can use onCleanup inside a computed getter to manage resources that need cleanup (like timers or subscriptions). The cleanup runs before the computed re-evaluates (when dependencies change), and also when the computed loses its last subscriber (to prevent resource leaks).

import { signal, computed, onCleanup } from "elements-kit/signals";

const source = signal(0);

const derived = computed(() => {
  // Setup resource
  const id = setInterval(() => {
    // ...do something...
  }, 1000);

  // Register cleanup
  onCleanup(() => clearInterval(id));

  return source() * 2;
});

This ensures that any resources created inside the computed are always cleaned up at the right time.

---

batch

Defers all signal notifications until the batch completes. Use it to group multiple writes into a single update pass — avoids intermediate re-renders.

import { signal, effect, batch } from "elements-kit/signals";

const x = signal(1);
const y = signal(2);

effect(() => console.log(x(), y()));
// → 1 2  (initial run)

// Without batch: effect would run twice (once per write)
batch(() => {
  x(10);
  y(20);
});
// → 10 20  (single run)

---

untracked

Reads a signal without creating a dependency. The current effect will not re-run when that signal changes.

import { signal, effect, untracked } from "elements-kit/signals";

const count  = signal(0);
const secret = signal("hidden");

effect(() => {
  // Tracked — effect reruns when count changes
  console.log("count:", count());

  // Untracked — effect does NOT rerun when secret changes
  console.log("secret:", untracked(() => secret()));
});

count(1);    // triggers re-run
secret("x"); // silent — not a dependency

Mutating vs. reassigning

Arrays and objects are passed by reference. Mutating them (push, pop, arr[0] = x) doesn’t notify subscribers — the signal value (reference) hasn’t changed.

const items = signal<string[]>([]);

// ❌ Won't trigger
items().push("Hello");

Option 1 — Mutation + trigger (for expensive data):

const items = signal<string[]>([]);

items().push("hello");
trigger(items);  // ✅ Mutate in place, then notify

Option 2 — Reassignment:

const items = signal<string[]>([]);

items([...items(), "hello"]);  // ✅ Creates new array

The same applies to objects:

const user = signal({ name: "Alice" });

// ❌ Won't trigger
user().name = "Bob";

// ✅ Reassignment
user({ ...user(), name: "Bob" });

// ✅ Or mutation + trigger
user().name = "Bob";
trigger(user);

---

@reactive decorator

Backs a class field with a signal transparently. The field reads and writes naturally — no () needed on the consumer side.

import { reactive, computed } from "elements-kit/signals";

class Counter {
  @reactive()
  count = 0;

  doubled = computed(() => this.count * 2);
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)
}

const c = new Counter();
c.count = 5;
c.doubled(); // → 10

@reactive is equivalent to a private signal + get/set accessor — it just removes the boilerplate. Works with computed too: pass the signal source to make a field read-only.

class Store {
  #items = signal<string[]>([]);

  // Read-only reactive field backed by a computed
  @reactive((s) => computed(() => s.#items().length))
  count = 0;
}

---

Store

A store is a class with @reactive fields. It holds state — no render(), no DOM. See Stores for full documentation.

See also

• Stores — shared reactive state.
• Elements — use signals as JSX children/props.
• Promise — reactive state over any Promise.
• Async — start/stop/run a reactive async controller.