State is a variable the page is watching

Start here·4 min· Assumes: reading a .tsrx filereading a .tsrx file

You already know how to count in JavaScript.

let countlet count: number = 0;
countlet count: number++;

Put count on the screen, run count++, and the screen will not change. Nothing is wrong with the variable. Nothing told the page to care about it.

state() is how you tell the page to care.

let countlet count: any = statestate · Watched valueDeclares a variable the page follows, which you read and assign exactly like any other variable.(0);

Still a let. Still starts at zero. You still read it by writing count and change it by writing count++. The one difference is that any part of your markup that used count now updates when count changes.

Here it is running. Click it a couple of times, with a beat between clicks:

That button is this file, all of it:

import { state } from '@markless/core';

export default function Counterfunction Counter(): Element() @{@{ · Component bodyOpens the body of a component, where ordinary statements and the markup they produce sit together.
	let countlet count: number = statestate · Watched valueDeclares a variable the page follows, which you read and assign exactly like any other variable.(0);

	<button(property) button: GlobalAttributes & MarklessAttributes<HTMLButtonElement> & NativeEventAttributes<HTMLButtonElement> & FormAttributes & { onClickonClick · Event handlerRuns when this element fires the matching DOM event, and receives the native event object.={() => countlet count: number++}>Clicked {count} times</button(property) button: GlobalAttributes & MarklessAttributes<HTMLButtonElement> & NativeEventAttributes<HTMLButtonElement> & FormAttributes & {>
}

count++ is the only thing the click does. No update call, no second name for the variable. The number inside the button is the only thing on the page that changes.

Only the parts that read it change

Two numbers, side by side. The first is a state variable. The second is an ordinary number, drawn once with Math.random while the component rendered and never touched again.

Click the button, and watch which one moves:

The watched number went up. The drawn number did not, and it will not, however long you keep clicking.

That is the whole lesson in one picture. Had the click re-run the component, a fresh random number would have appeared beside the new count. Instead it updated the one piece of text that read clicks and left the rest of the section exactly as the server sent it.

Here is the whole file:

import { state } from '@markless/core';

export default function TwoVariablesfunction TwoVariables(): Element() @{@{ · Component bodyOpens the body of a component, where ordinary statements and the markup they produce sit together.
	let clickslet clicks: number = statestate · Watched valueDeclares a variable the page follows, which you read and assign exactly like any other variable.(0);
	const drawnconst drawn: number = Math.floor(method) Math.floor(x: number): numberReturns the greatest integer less than or equal to its numeric argument.(Math.random(method) Math.random(): numberReturns a pseudorandom number between 0 and 1.() * 900) + 100;

	<section(property) section: GlobalAttributes & MarklessAttributes<HTMLElement> & NativeEventAttributes<HTMLElement>>
		<p(property) p: GlobalAttributes & MarklessAttributes<HTMLParagraphElement> & NativeEventAttributes<HTMLParagraphElement>>A watched variable: {clicks}</p(property) p: GlobalAttributes & MarklessAttributes<HTMLParagraphElement> & NativeEventAttributes<HTMLParagraphElement>>
		<p(property) p: GlobalAttributes & MarklessAttributes<HTMLParagraphElement> & NativeEventAttributes<HTMLParagraphElement>>An ordinary number, drawn once while this rendered: {drawn}</p(property) p: GlobalAttributes & MarklessAttributes<HTMLParagraphElement> & NativeEventAttributes<HTMLParagraphElement>>
		<button(property) button: GlobalAttributes & MarklessAttributes<HTMLButtonElement> & NativeEventAttributes<HTMLButtonElement> & FormAttributes & { onClickonClick · Event handlerRuns when this element fires the matching DOM event, and receives the native event object.={() => clickslet clicks: number++}>Add one to the watched variable</button(property) button: GlobalAttributes & MarklessAttributes<HTMLButtonElement> & NativeEventAttributes<HTMLButtonElement> & FormAttributes & {>
	</section(property) section: GlobalAttributes & MarklessAttributes<HTMLElement> & NativeEventAttributes<HTMLElement>>
}

So state() is not a special kind of storage, and it is not a box you have to open. It is a note to the compiler: someone is going to change this, so keep track of who is reading it.

What the compiler does with that note

It reads your whole component, so it knows three things before your app runs: where the value is created, everywhere it is read, and everywhere it is written. The specification puts it plainly: every read of that binding compiles to a graph read and every supported write compiles to a graph write, and that includes reads inside click handlers, inside markup, and inside helper functions in the same file.

Two consequences you can feel.

Your component function does not run again. Clicking that button runs the two characters you wrote, ++, and then updates the one piece of text that read count. Updates belong to the value, not to the component.

Objects update field by field. A scalar becomes one watched cell. An object becomes one watched cell per path, so this only touches the part of the page that read the status:

let userlet user: any = statestate · Watched valueDeclares a variable the page follows, which you read and assign exactly like any other variable.({ name: 'Ada', status: 'anonymous' });

user.statusany = 'ready';

Where state() works

Inside .tsrx files. That is the rule, and it is not an oversight.

Calling state() from a plain .ts file throws immediately, on purpose. Reactivity here is a feature of the language the compiler owns, not a library you can call from anywhere, and drawing that line is exactly what buys you the plain let and the plain count++. You find out at once rather than wondering later why a number never moves.

Coming from another framework?

If you have used one of the signal or hook based libraries, the thing to unlearn is the wrapper. There is no .value to read through, no setter function to call, and no character to add to the variable name. The reason Markless can do without them is that it compiles your file rather than watching your objects at runtime, so it already knows every place count is read. The tradeoff is the boundary above: this only works in .tsrx files.

Try it yourself

Open the counter file in your own project and add a second line of markup that also reads count, a paragraph above the button, say. Click once. Both places update, and you wrote nothing to connect them.

Next: values you never update by hand.