Reactivity

Add client-side state and DOM bindings with <script is:state> — opt-in, no Virtual DOM.

Aero is static-first: build-time { } interpolation renders once. When a page needs counters, toggles, form state, or UI that updates after load, enable reactivity. You keep writing .html with a fifth script type — no separate client framework required.

Reactivity defaults to false. Static sites ship no client binding runtime until you opt in.

Enable reactivity

aero.config.ts

import { defineConfig } from '@aero-js/core/config'

export default defineConfig({
	reactivity: true,
})

aero check reports templates that use reactive directives when the flag is off.

<script is:state>

State scripts run in the browser after mount. Top-level let declarations become signals wired to markup:

<script is:state>
	let count = 0
</script>

<section>
	<button on:click="{ count-- }">−</button>
	<span>{ count }</span>
	<button on:click="{ count++ }">+</button>
</section>

Rule	Detail
One per file	Only one <script is:state> per template
Signals	Top-level let bindings are reactive
Helpers	Top-level function declarations and const arrows are equivalent — use either style for handlers and shared logic that reads or updates state
Effects	Top-level $effect(() => { … }) runs imperative side effects when tracked signals change; return a function for cleanup
Imports	Hoisted into mount scope, same as client scripts
With is:build	Separate script blocks — state can read build-scope values to seed initial data (see below)

See Scripts for how state scripts fit the script taxonomy.

Seeding state from is:build

At render time, Aero runs <script is:build> then <script is:state> in the same scope. Declare data in the build script and assign it to state bindings:

<script is:build>
	import site from '@content/site.ts'

	const initialItems = site.featuredPosts
</script>

<script is:state>
	let items = initialItems
</script>

<ul>
	<li for="{ const post of items }" key="{ post.id }">{ post.title }</li>
</ul>

Build script runs once at compile (or request) time. Owned let values are serialized into a <script type="application/json" data-aero="state"> hydration payload so the client store matches the HTML on first paint. Derived bindings (for example let total = items.length) are recomputed at mount — they are not included in the payload.

Common sources for seed data:

Source	Example
Content collections	const posts = await getCollection('blog') → let items = posts
Page props	In components: const { count = Aero.bindable(0) } = Aero.props
Build constants	const limit = 10 → let pageSize = limit

Build-time { expression } in markup still renders static HTML. Use is:state when that data should stay reactive after load.

Collection state (objects, arrays, Map, Set)

Top-level let bindings can hold collection values. Aero wraps them in a coarse-grained reactive proxy: any nested mutation re-notifies effects that read that binding.

<script is:state>
	let formModel = { email: '', agree: false }
	let tags = new Set(['a', 'b'])
	let scores = new Map([[1, 'one']])
	let items = [1, 2, 3]
</script>

Pattern	Updates UI?
formModel.email = 'x'	Yes — in-place object field
items.push(4)	Yes — array mutation
tags.add('c')	Yes — Set method
scores.set(2, 'two')	Yes — Map method
items = [...items, 4]	Yes — whole binding replacement

Replacing the whole binding (items = next) still works and is a good fit when you want immutable list updates (for example with view transitions). In-place mutation is supported for ergonomics; both paths notify the same top-level signal.

Granularity: v1 is binding-level, not per-property. Reading items.length in a derived binding (let hasItems = items.length > 0) re-runs when items notifies — including after push, not only after items = ….

Hydration: Owned collection values serialize into <script type="application/json" data-aero="state">. Plain objects and arrays round-trip as JSON; Map and Set use __aero markers in the payload.

Non-reactive values: Primitives, functions, Date, class instances, DOM nodes, and typed arrays are stored as-is — mutating a Date in place does not notify.

Helpers and handlers

Declare helpers at the top level of <script is:state> with normal JavaScript — block or expression bodies, TypeScript parameter types, and mixed styles in one script:

<script is:state>
	import { withTransition } from '@scripts/utils/withTransition.ts'

	const createID = () => crypto.randomUUID().split('-').pop()

	let items = [{ id: createID() }]

	function add() {
		setItems([...items, { id: createID() }])
	}

	const remove = () => (items.length === 0 ? null : setItems(items.slice(1)))

	const setItems = next => withTransition(() => (items = next))
</script>

<button on:click="{ add() }">Add</button>
<button on:click="{ remove() }">Remove</button>

function foo() and const foo = () => … behave the same for templates and event handlers. Pure helpers that never touch reactive let bindings (for example createID above) stay at module scope; helpers that read or write state are available to bindings automatically.

What you can bind

With reactivity enabled, markup can update at runtime:

Pattern	Example
Text	{ count } or text="{ label }"
Events	on:click="{ count++ }", on:submit.prevent="{ save() }"
Visibility	show="{ open }"
Classes	class:is-active="{ active }"
Properties	disabled="{ saving }"
Forms	value="{ email }", checked="{ agree }"
Structure	Reactive if / else, keyed for, switch / case
Components	bind:count="{ count }" with Aero.bindable() in the child

Attribute names also accept aero-* and data-aero-* prefixes.

Hydration

Server-rendered HTML is the first paint. Aero emits a <script type="application/json" data-aero="state"> JSON payload with owned let binding values from render time (including values seeded from is:build). At mount, the client store reads that payload and attaches bindings — no manual hydration API.

Runtime access

For imperative inserts (hypermedia swaps or innerHTML), process bindings into the page store:

import aero from '@aero-js/core'

aero.getReactivityRuntime?.()?.process(element)

See Process runtime fragments.

Hypermedia

Reactivity alone covers client-only UI. Pair it with Hypermedia when fragments come from the server. busy and post-swap binding processing require both flags.

Next steps

Reactivity recipes

Common patterns: forms, lists, reactive props, when to use Alpine instead.

Bindings reference

Full syntax for events, show, html, class, property, and model bindings.

Reactive effects

Imperative side effects with $effect — web components, subscriptions, cleanup.

Structural updates

Reactive if, keyed for, and switch.

Reactive props

Share mutable state between parent and child components.