Documentation

Introduction

Tan Compose is a lightweight, zero-dependency library for authoring native Web Components with a declarative API. You describe a component once with describe() and register it with build(); the library handles Shadow DOM setup, theming via CSS custom properties, inline styles, lifecycle hooks, attribute reactivity, custom events, and slots.

Installation

Install from JSR for Deno or Node:

CDN / Deno import

You can also import directly in Deno or the browser:

Quick Start

Describe a component, then register it under a custom tag name. Custom tag names must be lowercase and contain a hyphen.

Then use it in HTML like any native element:

API Reference

describe(options)

Validates and returns a component description. As of v0.2.0, this function throws on invalid options (missing tag, malformed observedAttributes, etc.).

build(tagName, description)

Registers a custom element with the browser’s CustomElementRegistry and returns the registered tag name. The tagName must be lowercase and contain a hyphen (e.g. my-button); otherwise build() throws.

isComponentRegistered(tagName)

Returns true if a component with the given tag name has already been registered.

getRegisteredComponents()

Returns an array of every tag name registered through build() in the current document.

DescribeOptions

The full shape accepted by describe():

Component instance methods

Available as this inside lifecycle hooks and actions:

Lifecycle

Tan Compose components follow a deterministic lifecycle. Hooks run in the order below:

1. beforeMount — runs before the Shadow DOM is constructed. Use it to read attributes or seed state.
2. DOM construction — the Shadow DOM, root element, theme variables, styles, and children are built.
3. Mounted — the element is connected (connectedCallback).
4. afterMount — runs after the component is in the DOM. Safe place to attach listeners or call setState.
5. Updates — an attribute change in observedAttributes or a setState call triggers a re-render.
6. afterRender — runs after every render (initial and subsequent). Use for imperative DOM work that needs to repeat.
7. unmount — runs on disconnectedCallback. Use it to clean up timers and listeners.

Reactivity

There are two ways to update a Tan Compose component after it has mounted:

• State — call this.setState(key, value). As of 0.2.0, every setState call triggers an automatic re-render of the Shadow DOM.
• Attributes — declare them explicitly in observedAttributes. Only attributes listed there will trigger a re-render when changed via setAttribute() or directly in markup.

Typed properties (0.3+)

The props field declares typed properties on the host element. Setting one (el.rows = […]) triggers a re-render when the value differs. Initial values come from the matching attribute (string-coerced) when present, otherwise from default.

PropDef

Function templates (0.3+)

template may be a function that receives the render context and returns an HTML string. It runs on every render, so any expression in scope (props, state) is implicitly reactive.

ComponentCtx

Event delegation (0.3+)

The events field maps "<event-type> <css-selector>" keys to handlers. One listener per event type is attached at the shadow root; matches are resolved via composedPath(). Listeners are torn down on disconnect.

Handler signature is (event: Event, ctx: ComponentCtx) => void. Selector-less keys (e.g. "submit") match events that target the host directly.

Keyed list rendering (0.3+)

A child describe can take for: { items, key, render }. The renderer keeps a per-block cache keyed by key(item) and reuses DOM nodes between renders when item identity is unchanged. Stale items have their cleanups run.

ListConfig

Conditional rendering (0.3+)

A child describe can take if: (ctx) => boolean. When the predicate returns false, the subtree is omitted from the rendered output (no DOM created at all).

Putting it together: a real datatable

The features above compose into a paginated, filterable, sortable datatable. Open the examples page for the live version; here is the abridged source:

Because for is keyed by row.id, typing in the search box re-uses the same row nodes — the renderer just updates which slice is visible. No virtual DOM, no diff library: just the platform plus a couple hundred lines of glue.

Refs (0.4+)

The refs field is a name → CSS-selector map. After every render, the matching shadow-root elements are exposed as host.refs.<name> and ctx.refs.<name>. Selectors that match nothing yield null. Refs are re-queried on every render so they always point at the current DOM.

Form-Associated Custom Elements (0.4+)

Set formAssociated: true and the host calls attachInternals() automatically. If you declare a value prop, its setter syncs to internals.setFormValue so the host participates in form submissions and the validity API.

The internals are exposed at host.internals so you can call setValidity(), setFormValue() directly, or check internals.form.

Lifecycle hooks

Adopted stylesheets (0.4+)

theme and styles are compiled into CSSStyleSheet objects once per registered tag and applied to each instance via shadowRoot.adoptedStyleSheets. 100 instances of the same tag share 1–2 sheets instead of 100 inline <style> elements.

Falls back to per-instance <style> tags when constructable stylesheets aren't available. The change is invisible to user code — same CSS, same theming, less work for the renderer.

Migration: 0.1.x → 0.2.0

Version 0.2.0 is a minor release with breaking changes. Review each item below before upgrading:

• Attribute reactivity is now opt-in. Add a string array to observedAttributes to receive re-renders. The old behavior of inferring observed attributes from the attributes keys has been removed.
• setState auto-renders. You no longer need to call render() manually after updating state.
• describe() validates input. Invalid options (missing tag, non-array observedAttributes, non-function lifecycle hooks) now throw at description time.
• build() validates the tag name. The first argument must be lowercase and contain a hyphen. Names like MyButton or button are rejected.
• New unmount lifecycle hook. Pair it with afterMount for cleanup on disconnectedCallback.

Migration: 0.2.x → 0.3.0

Version 0.3.0 is additive — existing 0.2.x code continues to work. To opt in to the new features:

• Pass complex data via properties, not attributes. Add a props map and assign on the instance: el.rows = […]. JSON props are parsed from attributes when present and serialized only on read.
• Use function templates for derived text. Replace template strings that hard-code values with template: ({ props, state }) => "..." so changes flow through automatically.
• Replace manual afterMount wiring with events. Selector-keyed handlers attach once and clean up on disconnect, no per-render addEventListener calls.
• Use for for any list of three or more items. It's the only path to keyed DOM reuse, which matters the moment you have a filter input over a list.

Migration: 0.3.x → 0.4.0

Additive release. Existing 0.3.x code continues to work. Opt in to the new features as you need them:

• Replace this.shadowRoot.querySelector with refs. Declare the selectors once, get fresh references on every render.
• Add formAssociated: true + a value prop to anything that represents a form field. It will start submitting with <form> automatically.
• No code change is required for adopted stylesheets — the renderer picks the optimal path automatically wherever CSSStyleSheet.replaceSync is supported.

Migration: 0.4.x → 1.0.0

The 1.0 release is mostly additive. One subtle change to be aware of:

• for: now wraps in an element. If you had a child describe with ONLY for: (no other fields) and relied on items appearing ungrouped, they're now wrapped in a <div> by default. Set tag to override (e.g. tag: "tbody" when the parent is a <table>).
• children + for: can coexist. Code that caught the old "cannot set both" TypeError can drop the special case.