useState

Local object-style state with built-in methods and reactive updates.

import { useState } from 'mates';

const Form = () => {
  const [state, update] = useState({
    count: 0,
    step: 1,
    incr() { this.count += this.step; },       // auto-wrapped
    get doubled() { return this.count * 2; },  // version-cached getter
  });

  state.count;           // reactive read
  state.count = 5;       // direct assignment → re-render
  state.incr();          // method → re-render
  update((s) => {        // batch external mutation
    s.count = 0;
    s.step = 5;
  });

  return () => /* template */;
};

Overview

useState is the right primitive when local component state is naturally an object — fields, methods, and computed getters together. It returns [wrapper, update]: a read-tracked proxy and the underlying atom’s update handle.

Methods on the initial object are automatically wrapped so calling state.incr() runs the method and notifies subscribers — you do not call update() inside those methods. Direct assignment (state.count = 5) is also reactive.

Getters are version-cached: they recompute when state changes, not on every template read. Prefer this over a pile of separate atoms when the fields always move together.

Compared to atom / setter

Member	Status	Notes
`useState({…})`	object proxy	One reactive bag with methods + getters; component-local.
`atom(value)`	single value	Best for primitives or values shared via props / effects.
`setter`	manual notify	Plain `let` + re-render; no property-level tracking.

Async anti-pattern

// ✗ throws — async methods not supported
const [bad] = useState({
  async fetchData() { /* … */ }
});

// ✓ keep async outside useState
const load = asyncAction(async () => { /* … */ });

useState — object state with methods

Methods defined on the state object are automatically wrapped to trigger a re-render after they run. Getters work as derived values and are re-evaluated on each render.

import { html, useState, renderApp } from 'mates';

const App = () => {

const [form] = useState({

name: '',

email: '',

submitted: false,

// Methods auto-wrapped to trigger re-render

submit() {

this.submitted = true;

reset() {

this.name = '';

this.email = '';

this.submitted = false;

get isValid() {

return this.name.length > 0 && this.email.includes('@');

});

return () => html`

${form.submitted

? html`

<span class="tag tag-success m-b-10">Submitted!</span>

<p class="muted m-b-10">Email: <strong>${form.email}</strong></p>

<button class="btn-ghost" @click=${form.reset}>Reset</button>

</div>

: html`

<input .value=${form.name} @input=${e => form.name = e.target.value} placeholder="Name" />

<input .value=${form.email} @input=${e => form.email = e.target.value} placeholder="Email" type="email" />

<button class="btn-primary" ?disabled=${!form.isValid} @click=${form.submit}>Submit</button>

Direct assign + update()

Assign properties on the proxy for single-field edits. Use update(fn) to batch several mutations into one notify.

import { html, useState, renderApp } from 'mates';

const App = () => {

const [state, update] = useState({

count: 0,

step: 1,

get doubled() { return this.count * 2; },

});

const resetBoth = () => update((s) => {

s.count = 0;

s.step = 1;

});

return () => html`

<span class="overline">Count</span>

<span class="card-title">${state.count}</span>

</div>

<span class="overline">Doubled</span>

<span class="card-title">${state.doubled}</span>

</div>

<span class="card-title">${state.step}</span>

</div>

<button class="btn-primary" @click=${() => { state.count += state.step; }}>+step</button>

<button @click=${() => { state.step = state.step === 1 ? 5 : 1; }}>

step=${state.step}

</button>

<button class="btn-ghost" @click=${resetBoth}>update() reset</button>

API — useState

import { useState } from 'mates'

Prop / Option	Type	Default	Description
`useState(stateObj)`*	`[wrapper, update]`	—	Creates component-local reactive state from a plain object. Returns [wrapper, update]: wrapper is a read-tracked proxy; update is the underlying atom’s in-place mutator (a.update).
`wrapper.prop`	`T[prop]`	—	Reactive read — subscribes the current template / memo / effect so it re-runs when state changes.
`wrapper.prop = value`	`void`	—	Direct assignment on the proxy schedules a notify — equivalent to update(s => { s.prop = value }).
`wrapper.method()`	`void`	—	Methods from the initial object are auto-wrapped: the body runs, then update() notifies. No manual update() inside the method.
`wrapper.getter`	`derived`	—	Getters are version-cached — recomputed when state updates, not on every unrelated read.
`update(fn)`	`void`	—	Batch external mutation. fn receives the raw state object and may mutate it in place; one notify follows. No-op semantics follow atom.update (object values only).