Lifecycle Hooks

onMount, onCleanup, onError, onPaint, refs, and allMount.

import { html, atom, onMount, onCleanup, onPaint, onError, onAllMount } from 'mates';

const Panel = () => {
  const ready = atom(false);

  // Outer function only — register once for this host's lifetime
  onMount(() => {
    ready.set(true);
    return () => console.log('unmount'); // optional cleanup
  });

  onCleanup(() => { /* explicit teardown */ });
  onPaint(() => { /* after every paint */ });
  onError((err) => console.error(err));
  onAllMount(() => { /* this + all descendants mounted */ });

  return () => html`<p>${ready() ? 'ready' : '…'}</p>`;
};

Overview

Lifecycle hooks run at precise points in a component's life. Register them in the outer function (setup) — never inside the template or an effect. See Mental Model.

Order: outer setup → first render → onMount (DOM ready) → reactive updates → onPaint after each paint → unmount → onCleanup. onAllMount waits for this host and every descendant.

Atoms, effects, and framework hooks are disposed automatically on unmount. You only tear down what you created yourself (timers, third-party listeners, sockets).

Choose a lifecycle API

API	When	Prefer when
`onMount`	Once after DOM ready	Timers, focus, fetch-on-mount. Sync may return cleanup.
`onCleanup`	On unmount	Explicit teardown; required for async mounts.
`onPaint`	After every paint	Layout reads / post-paint work. Guard atom writes.
`onError`	Render/setup throw	Report + drive fallback UI via atoms.
`ref` / `setRef`	DOM handle	Imperative element access after attach.
`onAllMount`	Subtree mounted	Analytics / layout that needs children ready.

onMount with cleanup

import { html, atom, onMount, renderApp } from 'mates';

const Timer = () => {

const n = atom(0);

onMount(() => {

const id = setInterval(() => n.set(x => x + 1), 1000);

return () => clearInterval(id);

});

return () => html`

<p class="label">onMount + cleanup return</p>

</div>

};

renderApp(Timer, document.getElementById('app'));

onPaint — measure after paint

Fires after every paint. Compare before atom.set to avoid loops.

import { html, atom, onPaint, renderApp } from 'mates';

const Box = () => {

const size = atom('—');

onPaint(() => {

const el = document.getElementById('box');

if (!el) return;

const r = el.getBoundingClientRect();

const next = Math.round(r.width) + '×' + Math.round(r.height);

if (size() !== next) size.set(next);

});

return () => html`

<div id="box" class="card card-body p-20 center">Measure me</div>

</div>

};

renderApp(Box, document.getElementById('app'));

API — Lifecycle family (map)

import { onMount, onCleanup, onPaint, onError, onAllMount, ref, setRef } from 'mates'

Prop / Option	Type	Default	Description
`onMount(fn)`	`void`	—	Once after DOM ready. See /docs/lifecycle/on-mount.
`onCleanup(fn)`	`void`	—	On unmount. See /docs/lifecycle/on-mount.
`onPaint(fn)`	`void`	—	After every paint. See /docs/lifecycle/error-paint.
`onError(fn)`	`void`	—	Render/setup errors. See /docs/lifecycle/error-paint.
`ref / setRef`	`MatesRef / Directive`	—	DOM container + attach directive. See /docs/lifecycle/refs.
`onAllMount(fn)`	`void`	—	Subtree mounted. See /docs/lifecycle/all-mount.
`onReferenceChange(fn, deps)`	`void`	—	Re-run effect when deps change on update. Documented with refs.