Ity

A tiny dependency-free reactive app kernel for small browser apps, embeddable widgets, progressive SPAs, and local-first browser applications.

Ity 3 keeps the original Ity goal: do useful client-side app work without a framework stack, runtime dependencies, or a large bundle. The core stays platform-native and explicit: signals, computed values, effects, tagged HTML templates, DOM rendering, Web Components, and a modern router. V3 adds a small set of app-scale primitives and optional companion modules without trying to recreate React inside the core.

Why Ity 3?

Tiny runtime, no production dependencies in the core or companion modules.
Fine-grained reactive state with signal, computed, effect, and store.
Async UI primitives with resource, action, form, and formState.
Safe-by-default DOM templates: dynamic values become text unless explicitly marked with unsafeHTML.
Native Web Component support via component().
SPA routing with URLPattern support when available and a regex fallback when it is not.
Keyed structural rendering with repeat().
Static and hydration-friendly output through renderToString() and hydrate().
Scoped dependency flow through createScope(), ctx.provide(), and ctx.inject().
Runtime observability through observeRuntime().
Optional View Transition integration for same-document route/render updates.
Optional app-scale companion modules: ity/query, ity/forms, and ity/react.
V1-compatible Model, Collection, View, Application, and SelectorObject.

What's New In 3.0.0

Ity 3.0.0 expands the kernel without changing its native-first design:

repeat(items, key, render) for keyed structural list rendering.
hydrate() plus morph-based render() updates for progressive enhancement and SSR-style flows.
createScope() and scope-aware components and routers.
observeRuntime() for signals, resources, actions, and router activity.
Router.resource() and Router.action() for route-scoped async work.
Companion modules:
- ity/query for cache-backed async queries and optimistic mutations.
- ity/forms for nested form state, field arrays, explicit form.sync(), and richer submit controllers.
- ity/react for wrapping Ity custom elements inside React trees.
The deep Examples/OperationsWorkbench/index.html example now uses the v3 kernel and companion modules together.

What's New In 4.0.0

Ity 4.0.0 is a security-hardening major release:

Safe template bindings now block inline handler attributes and strip unsafe URL schemes such as javascript: and vbscript: from URL-bearing attributes and properties.
HTML-parsing sinks such as srcdoc and .innerHTML now require an explicit unsafeHTML(...) boundary so trusted markup stays deliberate.
SelectorObject string insertion is now text-by-default. Use Ity.unsafeHTML(...) if you intentionally want append, prepend, html, before, or after to parse trusted HTML strings.
SSR output from renderToString() now uses the same sink protections as the browser renderer, which removes a client/server consistency gap for unsafe attrs.
The Operations Workbench example sanitizer now blocks additional rich-text attack vectors such as srcdoc, xlink:href, and protocol-based data: navigation payloads.

Installation

npm install ity

import Ity, { signal, computed, html, render } from "ity";
import { createQueryClient, query } from "ity/query";
import { createFormKit } from "ity/forms";

The package ships ESM, CommonJS, browser IIFE, minified IIFE, source maps, and TypeScript declarations.

ity, ity/query, and ity/forms have no runtime package dependencies. ity/react is optional and expects react to already exist in the consuming application.

Examples

The repository includes small focused demos plus a deeper production-style app:

Examples/index.html
Examples/Calculator/index.html
Examples/Collection/index.html
Examples/Router/index.html
Examples/OperationsWorkbench/index.html: a local-first operations application that exercises repeat, scopes, runtime observation, ity/query, ity/forms, router resources/actions, component(), unsafeHTML(), and renderToString() together.

Run them locally with:

npm install
npm run examples:serve

Quick Start

import { signal, computed, html, render } from "ity";

const count = signal(0);
const doubled = computed(() => count() * 2);

render(() => html`
  <button @click=${() => count.update((n) => n + 1)}>
    Count: ${count}
  </button>
  <p>Doubled: ${doubled}</p>
`, "#app");

When count changes, only the reactive render effect reruns. Dynamic text is inserted as text, not parsed as HTML.

Signals

Signals are callable values.

const name = Ity.signal("Ada");

name();               // "Ada"
name.set("Grace");    // "Grace"
name("Hedy");         // callable setter
name.update((v) => v.toUpperCase());
name.peek();          // read without dependency tracking

`computed`

const first = Ity.signal("Ada");
const last = Ity.signal("Lovelace");
const full = Ity.computed(() => `${first()} ${last()}`);

full(); // "Ada Lovelace"

Computed values are lazy and cached. They invalidate when dependencies change.

`effect`

const stop = Ity.effect((onCleanup) => {
  const controller = new AbortController();
  onCleanup(() => controller.abort());

  console.log("Current value", full());
});

stop();

`batch` and `untrack`

Ity.batch(() => {
  first.set("Grace");
  last.set("Hopper");
});

const snapshot = Ity.untrack(() => full());

batch coalesces dependent effects. untrack reads without subscribing the current computation.

`store`

const state = Ity.store({ name: "Ada", count: 1 });

state.name; // reactive read
state.count = 2;
state.$patch({ name: "Grace" });
state.$snapshot(); // plain object

const unsubscribe = state.$subscribe((value) => {
  console.log(value);
}, { immediate: true });

store tracks object structure as well as values. Effects and subscribers that read $snapshot() rerun when keys are added or deleted.

Async UI

`resource`

resource() models loadable async data.

const user = Ity.resource(async ({ signal, previous, refreshId }) => {
  const response = await fetch(`/api/user?refresh=${refreshId}`, { signal });
  if (!response.ok) throw new Error("Failed to load user");
  return response.json() as Promise<{ name: string }>;
}, {
  initialValue: undefined,
  keepPrevious: true,
  onError(error) {
    console.error(error);
  }
});

Ity.render(() => Ity.html`
  ${user.loading() && Ity.html`<p>Loading...</p>`}
  ${user.error() && Ity.html`<p role="alert">${user.error().message}</p>`}
  ${user.data() && Ity.html`<h1>${user.data().name}</h1>`}
  <button @click=${() => user.refresh()}>Refresh</button>
`, "#app");

Each refresh aborts the previous in-flight refresh. Stale completions are ignored, failures are captured in error instead of being thrown from refresh(), and mutate(value) can update local state optimistically.

`action`

action() models async writes and other user-triggered effects.

const save = Ity.action(async (payload: { name: string }) => {
  const response = await fetch("/api/user", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(payload)
  });
  if (!response.ok) throw new Error("Save failed");
  return response.json();
});

Ity.render(() => Ity.html`
  <button ?disabled=${save.pending()} @click=${() => save({ name: "Ada" })}>
    ${save.pending() ? "Saving..." : "Save"}
  </button>
`, "#app");

Actions expose data, error, pending, pendingCount, status, submit(), run(), with(), from(), and reset().

`form`

form() wraps action() for native forms.

const signup = Ity.form(async (data) => {
  const response = await fetch("/signup", {
    method: "POST",
    body: data
  });
  if (!response.ok) throw new Error("Signup failed");
  return response.json();
}, { resetOnSuccess: true });

Ity.render(() => Ity.html`
  <form @submit=${signup.onSubmit}>
    <input name="email" type="email" required>
    <button ?disabled=${signup.pending()}>Join</button>
    ${signup.error() && Ity.html`<p role="alert">${signup.error().message}</p>`}
  </form>
`, "#app");

For direct DOM event wiring that should stay inside the controller error model, prefer signup.handleSubmit over signup.onSubmit.

`formState`

formState() adds field-level state on top of native forms.

const draft = Ity.formState({
  title: "",
  ownerId: "ava",
  urgent: false
}, {
  validators: {
    title(value) {
      return value.trim() ? null : "Title is required.";
    }
  }
});

const saveDraft = draft.submit(async (values) => {
  return fetch("/tasks", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(values)
  });
});

Ity.render(() => Ity.html`
  <form @submit=${saveDraft.handleSubmit}>
    <input bind=${draft.bind("title", { name: "taskTitle" })}>
    <select bind=${draft.bind("ownerId", { type: "select" })}></select>
    <label>
      <input type="checkbox" bind=${draft.bind("urgent", { type: "checkbox" })}>
      Urgent
    </label>
    ${draft.errors.title && Ity.html`<p role="alert">${draft.errors.title}</p>`}
  </form>
`, "#app");

formState() exposes values, initialValues, errors, touched, dirty, valid, field(name), bind(name), set(), reset(), validate(), markTouched(), and submit().

V3 Bridges

`repeat`

Use repeat() when list items need keyed identity:

const tasks = Ity.signal([
  { id: "a", title: "Draft launch brief" },
  { id: "b", title: "Ship release notes" }
]);

Ity.render(() => Ity.html`
  <ul>
    ${Ity.repeat(tasks(), (task) => task.id, (task) => Ity.html`
      <li>${task.title}</li>
    `)}
  </ul>
`, "#app");

`hydrate`

hydrate() attaches bindings to existing markup instead of replacing it:

Ity.hydrate(() => Ity.html`
  <button @click=${() => console.log("ready")}>Hydrated</button>
`, "#app");

`createScope` and `observeRuntime`

Scopes let components and routers share services without a framework-wide context object. Runtime observation gives a lightweight event stream for debugging and tooling.

const scope = Ity.createScope({ name: "app" });
scope.provide("apiBase", "/api");

const stop = Ity.observeRuntime((event) => {
  console.log(event.type, event.name);
});

`ity/query`

Use ity/query when async data should be cached and invalidated:

import { createQueryClient, query, mutation } from "ity/query";

const client = createQueryClient();
const user = query(client, ["user", "42"], async () => {
  const response = await fetch("/api/users/42");
  return response.json();
});

const saveUser = mutation(client, async (payload) => {
  const response = await fetch("/api/users/42", {
    method: "POST",
    body: JSON.stringify(payload)
  });
  return response.json();
}, {
  invalidate: [["user", "42"]]
});

`ity/forms`

ity/forms is the richer companion to core formState(). Use it when the form needs nested paths, field arrays, or explicit syncing before structural mutations:

import { createFormKit } from "ity/forms";

const draft = createFormKit({
  title: "",
  checklist: [{ label: "" }]
});

const checklist = draft.array("checklist");

`ity/react`

Use ity/react when Ity custom elements need to live inside a React tree:

import { wrapCustomElement } from "ity/react";

const UserCard = wrapCustomElement("user-card", {
  events: {
    onChoose: "choose"
  }
});

ity/react is a bridge, not part of the dependency-free core. Consumers using that entrypoint should already have react installed.

HTML Templates

html creates a template result. Use render to mount it.

const title = Ity.signal("Dashboard");

Ity.render(() => Ity.html`
  <section class=${["panel", "primary"]}>
    <h1>${title}</h1>
    <input .value=${title}>
    <button ?disabled=${false} @click=${() => title.set("Updated")}>
      Rename
    </button>
  </section>
`, "#app");

Supported bindings:

Text/content: ${value}.
Events: @click=${handler} or @click=${[handler, options]}.
Properties: .value=${value}.
Boolean attributes: ?disabled=${condition}.
Attributes: href=${url}, class=${["a", "b"]}, class=${{ active: true }}.
Style objects: style=${{ color: "red" }}.
Nested templates, DOM nodes, arrays, and signals.

Unsafe HTML

Dynamic values are safe text by default. If you intentionally want to parse a string as HTML, mark that boundary explicitly:

Ity.html`<article>${Ity.unsafeHTML(trustedHtmlString)}</article>`;

Only pass trusted content to unsafeHTML. If your application allows rich HTML from a less trusted source, wire in your sanitizer:

const htmlPolicy = Ity.createConfig({
  sanitizeHTML(value) {
    return DOMPurify.sanitize(value);
  }
});

Ity.render(() => Ity.html`
  <article>${Ity.unsafeHTML(userProvidedHtml)}</article>
`, "#app", { config: htmlPolicy });

You can still sanitize one boundary without changing configuration:

Ity.unsafeHTML(markdownHtml, { sanitize: sanitizeMarkdownOutput });

Ity.configure({ sanitizeHTML }) still exists for process-wide setup, but createConfig() is the better fit for multi-app pages, tests, and SSR.

Ity does not bundle a sanitizer. Sanitization policy depends on the content source and threat model, and most production apps already standardize that choice separately.

Safe bindings also block inline handler attributes such as onclick=${"..."} and strip dangerous URL schemes such as javascript: from URL-bearing attributes. If you intentionally need HTML-parsing sinks like srcdoc or .innerHTML, pass Ity.unsafeHTML(...) so the boundary stays explicit.

Render Options

const stop = Ity.render(view, "#app", {
  reactive: true,
  transition: true,
});

stop();

transition: true uses document.startViewTransition() when the browser supports it and falls back to a normal render otherwise.

Static and SSR Output

const markup = Ity.renderToString(() => Ity.html`
  <article>
    <h1>${title}</h1>
    ${Ity.unsafeHTML(trustedBodyHtml)}
  </article>
`);

renderToString escapes dynamic text and attributes, skips event/property bindings that only make sense in the browser, preserves boolean attributes, and keeps unsafeHTML explicit.

Components

component() defines a custom element and renders it with Ity templates.

Ity.component("ity-counter", {
  attrs: ["label"],
  shadow: true,
  styles: `
    button {
      border: 0;
      border-radius: 999px;
      padding: 0.65rem 1rem;
    }
  `,
  setup(ctx) {
    const label = ctx.attr("label");
    const count = Ity.signal(0);

    return () => Ity.html`
      <button @click=${() => count.update((n) => n + 1)}>
        ${label}: ${count}
      </button>
    `;
  }
});

Component context:

ctx.host: the custom element instance.
ctx.root: the shadow root or host render root.
ctx.attr(name): a signal for an observed attribute.
ctx.prop(name): a signal for a declared component property.
ctx.emit(name, detail, options): dispatch a composed bubbling custom event.
ctx.effect(fn): an effect that is disposed on disconnect.
ctx.onConnected(fn) and ctx.onDisconnected(fn): lifecycle hooks.

Structured props are declared with props:

Ity.component("user-card", {
  props: ["user"],
  shadow: true,
  setup(ctx) {
    const user = ctx.prop<{ name: string }>("user");
    return () => Ity.html`<h2>${user()?.name || "Unknown"}</h2>`;
  }
});

If a tag has already been defined, component() returns the existing constructor instead of throwing.

Router

const router = new Ity.Router({ transition: true });

router.add("/users/:id", (params, ctx) => {
  console.log(params.id, ctx.query, ctx.hash);
});

router.add("/files/*", (params) => {
  console.log(params.wildcard);
});

router.navigate("/users/42?tab=profile#panel=activity");

The router:

Uses native URLPattern when available.
Falls back to a small internal matcher for :param and * segments.
Parses query and hash params.
Exposes router.current as a signal.
Intercepts same-origin in-base links from the document and composes bindable links with router.link(path).
Honors base for matching, navigation, link interception, and Navigation API events.
Intercepts same-origin Navigation API events when the API is available.
Supports navigate(path, { replace, transition }).
Supports href(path) and link(path, attrs) helpers for template authoring.
Supports start() and stop().
Runs cleanup functions returned from route and notFound handlers.

router.link() is the preferred way to author links in templates and custom elements:

const router = new Ity.Router({ base: "/app" });

Ity.html`<a bind=${router.link("/users/42")}>User 42</a>`;

Route cleanup is useful when a route mounts a render effect, starts a subscription, or owns async work:

router.add("/dashboard", () => {
  const stop = Ity.render(() => Ity.html`<dashboard-page></dashboard-page>`, "#app");
  return stop;
});

For very small apps, use the convenience helper:

Ity.route("/settings", () => {
  Ity.render(Ity.html`<settings-page></settings-page>`, "#app");
});

V1 Compatibility

The original MVC API remains available:

const app = new Ity.Application();
const model = new Ity.Model({ data: { message: "Hello" } });

const view = new Ity.View({
  el: "#app",
  app,
  model,
  events: {
    "button": { click: "onClick" }
  },
  initialize() {
    this.model.on("change", this.render, this);
  },
  render() {
    this.select(".message").html(this.model.get("message"));
  },
  onClick() {
    this.model.set("message", "Updated");
  }
});

Compatibility classes:

Application: view registry and app-level event fan-out.
Model: data object, get, set, unSet, clear, events, sync.
Collection: model array, filtering, lookup, fetch, collection signal.
View: scoped element, delegated DOM events, event emitter, renderWith.
SelectorObject: jQuery-like scoped DOM traversal and mutation.

V1 models and collections also expose reactive state signals, so old and new code can be migrated incrementally.

SelectorObject

const view = new Ity.View({ el: ".parent" });

view
  .select(".item")
  .addClass("active")
  .attr("aria-current", true)
  .text("Selected")
  .parent()
  .find(".remove")
  .remove();

Supported methods include find, filter, first, last, parent, children, remove, before, after, append, prepend, html, empty, attr, text, on, off, addClass, removeClass, toggleClass, hasClass, and toArray.

Selector string insertion is text-by-default. Use Ity.unsafeHTML(...) when you intentionally want append, prepend, before, after, or html to parse a trusted HTML string.

Build

The repo targets Node 20+ and includes an .nvmrc pinned to the preferred local runtime. Running nvm use before build or release keeps local tooling in line with CI and avoids engine warnings.

nvm use
npm install
npm run build

This creates:

dist/ity.js
dist/ity.min.js
dist/ity.esm.js
dist/ity.esm.mjs
dist/ity.cjs.js
dist/ity.d.ts
Source maps

Test

npm test
npm run test:dist
npm run coverage
npm run perf:bench
npm run release:npm

The suite covers the v3 reactive runtime, companion modules, DOM templating, components, router, platform fallbacks, workbench performance regressions, and V1 compatibility.

Continuous integration runs coverage, distributable build verification, dist-bundle tests, and npm pack --dry-run on Node 20 and Node 22.

Migration

See MIGRATION.md for the full V1-to-v3 migration guide.

Browser Support

Ity 3 is built on standard browser APIs:

Custom Elements and Shadow DOM for components.
URLPattern when available, with an internal fallback.
document.startViewTransition() when available, with normal rendering as the fallback.
No dependency on the HTML Sanitizer API because it is not universally available. Ity keeps dynamic template values safe by using text nodes unless unsafeHTML is explicitly requested.

License

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Name		Name	Last commit message	Last commit date
Latest commit History 169 Commits
.github/workflows		.github/workflows
Examples		Examples
dist		dist
scripts		scripts
test		test
types		types
.gitignore		.gitignore
.nvmrc		.nvmrc
Ity.ts		Ity.ts
LICENSE		LICENSE
MIGRATION.md		MIGRATION.md
README.md		README.md
forms.ts		forms.ts
jest.config.ts		jest.config.ts
node-globals.d.ts		node-globals.d.ts
package-lock.json		package-lock.json
package.json		package.json
path.d.ts		path.d.ts
query.ts		query.ts
react.ts		react.ts
reportCoverage.js		reportCoverage.js
rollup.config.js		rollup.config.js
setup.sh		setup.sh
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Ity

Why Ity 3?

What's New In 3.0.0

What's New In 4.0.0

Installation

Examples

Quick Start

Signals

computed

effect

batch and untrack

store

Async UI

resource

action

form

formState

V3 Bridges

repeat

hydrate

createScope and observeRuntime

ity/query

ity/forms

ity/react

HTML Templates

Unsafe HTML

Render Options

Static and SSR Output

Components

Router

V1 Compatibility

SelectorObject

Build

Test

Migration

Browser Support

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`computed`

`effect`

`batch` and `untrack`

`store`

`resource`

`action`

`form`

`formState`

`repeat`

`hydrate`

`createScope` and `observeRuntime`

`ity/query`

`ity/forms`

`ity/react`

Packages