Quick start

Components are plain functions. Call .toString() to get an HTML string for server rendering or static generation.

import { t } from 'kensington';
function profileCard(name, title) {
  return t.article({ class: 'profile' },
    t.h2(name),
    t.p({ class: 'title' }, title),
    t.a({ href: `/users/${name.toLowerCase()}` }, 'View profile'),
  );
}
profileCard('Alice', 'Senior Engineer').toString();

<article class="profile">
  <h2>Alice</h2>
  <p class="title">Senior Engineer</p>
  <a href="/users/alice">View profile</a>
</article>

For live DOM, call .toElement() instead. Pass a signal() anywhere a static value is accepted and the DOM updates automatically when the value changes.

import { t, signal, computed } from 'kensington';
const count = signal(0);
const label = computed(() => count.get() === 1 ? 'item' : 'items');
const counter = t.div([
  t.p([count, ' ', label]),
  t.button({ onclick: () => count.set(n => n + 1) }, '+'),
  t.button({ onclick: () => count.set(n => n - 1) }, '-'),
]).toElement();
document.body.append(counter);

import { t, signal, computed, Signal } from 'kensington';
const count: Signal<number> = signal(0);
const label = computed(() => count.get() === 1 ? 'item' : 'items');
const counter = t.div([
  t.p([count, ' ', label]),
  t.button({ onclick: () => count.set(n => n + 1) }, '+'),
  t.button({ onclick: () => count.set(n => n - 1) }, '-'),
]).toElement();
document.body.append(counter);

Signals work as content, as attribute values, inside style objects, and in the prop key. Calling .toElement() wires up all updates.

Why Kensington?

We wanted flying cars , instead we got 140 thousand hours of React tutorials. We find ourselves spending more time trying to parse framework docs, and less time actually writing code. Kensington hopes to alleviate some of these ails by presenting a simpler alternative to the frameworks. The basics can be learned in a few minutes, and the entire API can be learned in half an hour. Kensington handles the structural work automatically, leaving a simple api for a dev to parse.

There are no magic attributes to memorize, and no new HTML templating language to learn. It is plain JavaScript function and method calls. If you can read the code, you can guess what it does, even before reading the docs.

Comprehensive typing, lint rules, IDE plugins, and server integrations help keep your code clean. In case you let robots write your code, Kensington is very AI-friendly, and produces code that is simple enough to be reviewable by a human.

// TypeScript sees a plain string. No attribute checking inside.
const html = htm`<input typ="checkbox">`;
//                       ^^^ typo, no error raised

// t.input knows the InputAttributes interface
t.input({ typ: 'checkbox' });
// TypeScript: 'typ' does not exist on InputAttributes

// attrs typed as Record<string, any>, no element-specific checking
h('input', { typ: 'checkbox' });
//            ^^^ typo, no error raised

// t.input knows the InputAttributes interface
t.input({ typ: 'checkbox' });
// TypeScript: 'typ' does not exist on InputAttributes

Building HTML

Elements & content

Every HTML, SVG, and MathML element is available as a method on t . All call forms work:

t.div({ id: 'app' }, 'text');      // options + content
t.div({ id: 'app' });              // options only
t.div('text');                     // content only
t.div([t.p('a'), t.p('b')]);       // content array
t.div();                           // empty

Void elements take only options (no content):

t.input({ type: 'checkbox', checked: true });
t.br();
t.meta({ charset: 'utf-8' });

Content can be strings, numbers, tags, arrays, or any mix. Arrays are flattened:

t.p(['Count: ', 42, t.strong(' items')]).toString();
// <p>Count: 42<strong> items</strong></p>

Attributes accept camelCase keys (converted to kebab-case), class as an array, and style as a plain object. Boolean attributes are included when true , omitted when false .

t.div({ id: 'app', class: ['card', 'shadow'] });         // class as array
t.input({ type: 'checkbox', checked: true });            // boolean attribute
t.p({ style: { color: 'red' } }, 'Warning');             // style object
t.div({ dataBsToggle: 'collapse' });                     // camelCase → data-bs-toggle

For the full reference including nested objects, data-* , aria-* , event handlers, and DOM properties, see Attributes & options in the Advanced section.

Rendering lists

Pass an array anywhere content is expected. Each element is rendered in sequence, so .map() is the natural way to render a list of items.

const items = ['Apples', 'Oranges', 'Pears'];
t.ul(items.map(item => t.li(item)));
// Nested: combine with objects
t.tbody(rows.map(row =>
  t.tr([t.td(row.name), t.td(row.role)])
));

<ul>
  <li>Apples</li>
  <li>Oranges</li>
  <li>Pears</li>
</ul>

Todo list example → Form from schema example →

Conditionals

Falsy values ( null , undefined , false , '' ) are silently dropped from content. No conditional wrappers needed.

t.ul([
  t.li('always shown'),
  isLoggedIn && t.li(t.a({ href: '/logout' }, 'Log out')),
  show ? t.li('yes') : null,
]);

If isLoggedIn is false, the second li is simply absent from the output. The null in the third slot is dropped the same way.

Live filter example →

Components & reuse

Plain functions work as components. No framework, no lifecycle, no magic. A component is just a function that takes arguments and returns a tag.

function card(heading, body) {
  return t.div({ class: 'card' }, [
    t.div({ class: 'card-header' }, heading),
    t.div({ class: 'card-body' }, body),
  ]);
}
t.div({ class: 'card-grid' }, [
  card('Alice', t.p('Role: Admin')),
  card('Bob',   t.p('Role: Editor')),
]);

<div class="card-grid">
  <div class="card">
    <div class="card-header">Alice</div>
    <div class="card-body">
      <p>Role: Admin</p>
    </div>
  </div>
  <div class="card">
    <div class="card-header">Bob</div>
    <div class="card-body">
      <p>Role: Editor</p>
    </div>
  </div>
</div>

Because .toString() and .toElement() are just methods, the same component works in Node and in the browser with no changes.

Server rendering example → Express render helper example → Framework integration example → Elysia example →

Tag methods are bound to the instance, so you can destructure them and call them directly:

const { div, p, ul, li, span } = t;
div({ class: 'card' }, [
  p('Methods are bound, so destructuring works anywhere.'),
  ul([li('item one'), li('item two')]),
]);

Browser DOM

Standard event handler attributes ( onclick , oninput , etc.) accept a function (wired via addEventListener ) or a string (set via setAttribute ). For custom events, use the on key with a plain object mapping event names verbatim to handlers. SVG and MathML elements get the correct namespace automatically.

import { t } from 'kensington';
const button = t.button({ type: 'button' }, 'Click me').toElement();
document.body.append(button);
// custom events: names are passed verbatim to addEventListener
const el = t.div({
  on: {
    bricksSelectorChange: e => console.log(e.detail),
    'my-custom-event':    e => console.log(e.detail),
  },
}).toElement();
// SVG gets the correct SVGElement namespace
const svg = t.svg({ viewBox: '0 0 100 100' }, [
  t.circle({ cx: 50, cy: 50, r: 40, fill: 'steelblue' }),
]).toElement();
document.body.append(svg);

Use .toElement() to get a live DOM element. It is safe to call before the element is mounted.

Counter example →

Reactive Data

Wrap any value in signal() and pass it into a tag. When the signal changes, only the affected text node or attribute updates in place. Nothing re-renders.

import { t, signal } from 'kensington';
const count = signal(0);
document.body.append(
  t.div([
    t.p(['Count: ', count]),
    t.button(
      { onclick: () => count.set(count.value + 1) },
      '+1'
    ),
  ]).toElement()
);

Full reactivity guide: computed, effects, lifecycles, server rendering →

TypeScript

Attribute types

Types are generated directly from the HTML, SVG, and MathML living standards. Attribute names are checked, attribute values are typed as enums, booleans, or numbers as appropriate, and the style object is typed with csstype . You get a compile-time error when a value is wrong.

Content model

Strict containers enforce which children are valid at compile time. Passing a div to t.tr() is a type error. Branded return types ( TdTag , LiTag , ImgTag , etc.) extend ContentTag , so existing code that types values as ContentTag still works.

TypeScript types are also generated for custom elements and module augmentation. See Custom elements in the Advanced section.

Tooling

HTML → Kensington

The kensington CLI converts existing HTML to Kensington code. Paste it in the terminal, pipe a file, or pass a filename.

<nav class="navbar" aria-label="main" aria-expanded="true">
  <a href="/" class="nav-link">Home</a>
  <a href="/about" class="nav-link">About</a>
</nav>

t.nav({ class: "navbar", aria: { label: "main", expanded: "true" } }, [
  t.a({ href: "/", class: "nav-link" }, "Home"),
  t.a({ href: "/about", class: "nav-link" }, "About"),
])

If ESLint or Prettier is present in the working directory, the converter runs the formatter over the output.

IDE plugins

CSS class completions and diagnostics inside Kensington class strings. Both plugins read your local stylesheets and any CDN stylesheets linked via t.link in your project.

Available for VS Code and JetBrains IDEs. Both plugins also wire up Go to Definition and Find Usages between CSS selectors and Kensington templates.

ESLint plugin

kensington-eslint-plugin catches common signal mistakes at lint time: writes inside computed derivations, orphaned effects, async pitfalls, and more. Requires ESLint 9+ and Node 18+.

npm install --save-dev kensington-eslint-plugin

Add the recommended config to your eslint.config.js :

import kensington from 'kensington-eslint-plugin';
export default [
  kensington.configs.recommended,
  // ...your other configs
];

DevTools panel

import 'kensington/devtools';

A floating overlay that tracks every signal, effect, and DOM binding live. Click the K badge in the bottom-right corner to open it. Guard the import so it does not run in production. See Devtools on the Reactive data page for setup options and a full tab reference.

Server packages

Drop-in view rendering for Express and Fastify. Each package attaches a renderView() method to the response that applies a layout, merges locals, and sends the HTML string. See the kensington-express and kensington-fastify examples for full usage.

AI assistants

Kensington ships an AGENTS.md file at the package root. It is a compact, single-file reference of the full API: method signatures, attribute rules, constructor options, TypeScript types, the CLI, and working examples. AI coding assistants can read it to answer questions and generate accurate Kensington code.

Using it

Most AI editors and assistants let you add files as context. Point yours at AGENTS.md and it will have everything it needs to work with Kensington correctly:

• Claude Code : reference node_modules/kensington/AGENTS.md in your conversation, or add it to your project's CLAUDE.md .
• Cursor / Windsurf : add the file to your .cursorrules context or drag it into the chat.
• Any chat interface : paste the contents directly into the conversation before asking questions about Kensington.

Attributes & options

Dev vs production

Two settings are worth flipping between local development and production. Use them together to catch attribute typos and bad values during development while shipping a small bundle to users.

Validation in development

By default, validationLevel is 'off' . In development, set it to 'warn' or 'error' so invalid attribute names and values are reported at runtime instead of silently rendering. TypeScript catches most issues at compile time. This catches the rest (dynamic attribute names, JS callers, and any code path TypeScript can't reach).

import Kensington from 'kensington';
const t = new Kensington({ validationLevel: 'error' });
t.input({ type: 'checkbox' });   // fine
t.input({ type: 'notatype' });   // throws. Not an allowed value
t.div({ unknownAttr: 'x' });     // throws. Not a known attribute

See Validation below for the full options and behavior.

Slim build for production

The slim build is a separate bundle that ships without per-element attribute spec data. The minified output drops from ~148 KB to ~27 KB, about 5× smaller. The public API is identical. Tags, attributes, signals, and hydration all work the same.

Since the slim build has no spec data, runtime validation is unavailable. The constructor throws if you set validationLevel to anything other than 'off' .

import Kensington from 'kensington/dist/slim';
const t = new Kensington();   // validationLevel defaults to 'off'
t.div({ class: 'card' }, t.p('Hello'));

Wiring it up with Vite

Use a Vite alias to swap the import target by build mode. Your application code stays as import Kensington from 'kensington' everywhere. Vite resolves to the full build in dev and the slim build in production.

// vite.config.js
import { defineConfig } from 'vite';
export default defineConfig(({ mode }) => ({
  resolve: {
    alias: mode === 'production'
      ? { kensington: 'kensington/dist/slim' }
      : {},
  },
}));

Pick the validation level from Vite's build environment so dev gets runtime checks and prod gets the no-op fast path.

// src/t.js
import Kensington from 'kensington';
export const t = new Kensington({
  validationLevel: import.meta.env.DEV ? 'error' : 'off',
});

Use t everywhere in your app. npm run dev loads the full build with errors on bad attributes. npm run build produces a bundle backed by the slim runtime.

The same pattern works with other bundlers. See Rollup , esbuild , and Webpack in the examples page for equivalent setups.

Constructor options

import Kensington from 'kensington';
const t = new Kensington({
  validationLevel: 'warn',        // 'off' | 'warn' | 'error', default 'off'
  additionalNamespaces: ['hx'],   // allow hx-* (htmx), x-* (alpine), etc.
  additionalGlobalAttributes: {   // allow specific attributes on every element
    popover: ['auto', 'manual'],  // string enum
    nonce: String,                // any string value
    inert: Boolean,               // boolean attribute
  },
  indentationLevel: 2,            // spaces per indent, default 2, 0 to disable
  logger: msg => myLogger(msg),   // receives validation warnings, default console.log
});

Validation

• Attribute names: checked against the HTML/SVG/MathML spec. data-* , aria-* , additionalNamespaces , and additionalGlobalAttributes are always allowed.
• Attribute values: checked against allowed types/literals (e.g. type on input only accepts known values; id must not start with a digit).
• Style object values: non-string/number values (other than undefined ) are flagged.

const t = new Kensington({ validationLevel: 'error' });
t.div({ class: 'ok' });         // fine
t.div({ unknownAttr: 'x' });    // throws: not a known attribute
t.input({ type: 'checkbox' });  // fine
t.input({ type: 'notatype' });  // throws: not an allowed value

Custom elements

import Kensington from 'kensington';
class MyEngine extends Kensington {
  myCard = this.createCustomTag('my-card', {
    'card-type': ['primary', 'secondary'],            // allowed string literals
    'loading': Boolean,                               // boolean attribute
    'max-items': Number,                              // numeric attribute
    'score': v => typeof v === 'number' && v <= 100,  // custom validator function
  });
}
const t = new MyEngine();
t.myCard({ 'card-type': 'primary' }, t.p('content')).toString();
// → <my-card card-type="primary">
//     <p>content</p>
//   </my-card>

To extend a built-in element with extra attributes, import its attribute object from kensington/attributes and spread it into createCustomTag :

import Kensington from 'kensington';
import { buttonAttributes } from 'kensington/attributes';
class MyEngine extends Kensington {
  button = this.createCustomTag('button', {
    ...buttonAttributes,
    popovertarget: String,  // add an attribute not yet in the spec data
  });
}
const t = new MyEngine({ validationLevel: 'error' });
t.button({ type: 'button', popovertarget: 'my-popover' }, 'Open').toString();

Every element in the spec has a corresponding named export ( divAttributes , inputAttributes , …) available from kensington/attributes .

Use ContentMethod<T> to type a custom element method, and module augmentation to allow custom attribute namespaces without a subclass:

import Kensington, { type ContentMethod } from 'kensington';
class MyEngine extends Kensington {
  myCard: ContentMethod<{ 'card-type'?: 'primary' | 'secondary'; loading?: boolean }> =
    this.createCustomTag('my-card', { 'card-type': ['primary', 'secondary'], loading: Boolean });
}
declare module 'kensington' {
  interface NameSpaceAttributes {
    [key: `hx${string}`]: string | object;
  }
}
t.div({ hxBoost: 'true' });  // now valid

htmx integration example → Tailwind example → Alpine.js example →

Persist effects

By default, .toElement() stops signal effects permanently when an element is removed from the DOM. For elements that will be moved or temporarily removed and re-inserted, add persist: true to the tag options. Effects are paused on removal and resume automatically on re-insertion, across any number of cycles.

// Without persist: true, the reconciler's insertBefore moves during drag-reorder
// trigger dom-tracker to permanently stop the item's signal effects (class, checked, etc.).
// With persist: true, effects pause on removal and resume when the node is re-inserted.
const item = t.li({ 'data-key': task.id, class: statusClass, persist: true }, [
  t.input({ type: 'checkbox', checked: task.done }),
  t.span(task.text),
]);

persist: true is silently ignored in .toString() and has no effect on server-side rendering. It only changes behavior when an element created by .toElement() is removed and re-inserted into the DOM.

Raw HTML & comments

t.literal('<li>verbatim, HTML-encoded</li>');    // <script> tags flagged via validationLevel
t.unsafeLiteral('<li>trusted HTML, no encoding</li>');
t.inlineComment('hello world');          // <!-- hello world -->
t.inlineComment('line 1\nline 2');       // <!--\n  line 1\n  line 2\n-->

Preformatted text example →

Complete examples covering SSR, htmx, forms, icon reuse, and reactive patterns are on the Examples page .