State: a box with .value

Components often need to remember things. A product card remembers how many are in the cart; a gallery remembers which picture it's on; a form remembers what you typed. In weft that memory is state, and a piece of state is a box: state(0) makes a box holding 0, and you read and write it through .value.

When a plain variable isn't enough

Here's a gallery that should move to the next picture when you press Next. It keeps its position in a let:

<!-- example: skip deliberately broken: W041 is the point of the example -->

import { Button } from '@weft-js/warp'const pictures = ['Homenaje a la Neurocirugía', 'Floralis Genérica', 'Eternal Presence']export function Gallery() {  let index = 0  return (    <section>      <h2>{pictures[index]}</h2>      <Button onClick={() => index++}>Next</Button>    </section>  )}

Pressing Next changes index, but the heading never moves. The component body ran once, built the heading from index as it was then, and finished. Nothing reads index again, and nothing knows it changed.

The fix is to make it state. The catalog names a let that a handler changes and JSX reads W041, but this weft doesn't report it yet, so watch for it yourself. (A let that names a prop is different, and allowed: see Passing props.)

To update the page, a value needs two things:

1. It has to keep its value for as long as the component is on the page.
2. Changing it has to reach the parts of the page that show it.

A box does both.

Adding a box

Import state from @weft-js/core and make a box in the component body:

import { state } from '@weft-js/core'import { Button } from '@weft-js/warp'const pictures = ['Homenaje a la Neurocirugía', 'Floralis Genérica', 'Eternal Presence']export function Gallery() {  const index = state(0)  return (    <section>      <h2>{pictures[index.value]}</h2>      <Button onClick={() => (index.value = (index.value + 1) % pictures.length)}>Next</Button>    </section>  )}

Three changes: state(0) makes the box, the heading reads index.value, and the handler writes index.value. Now the heading follows:

Meet your first box

state(initial) returns an object of type State<T> with a value property. That's all a box is, from the outside:

const index = state(0)index.value        // read: 0index.value = 1    // writeindex.value++      // read, then write: 2

.value is how weft knows who reads what. When JSX reads index.value, that spot in the page subscribes to the box. When a handler writes it, the box tells exactly those spots, and they update. Gallery doesn't run again; nothing else on the page does either.

index itself is const, and stays the same box for the life of the component. Only what's inside changes. That's why the box can keep its value: the body ran once, but the box it made lives on in every closure and binding that holds it.

The type comes from the initial value. When it can't, say it:

import { state } from '@weft-js/core'type Draft = { text: string; at: number }export function makeBoxes() {  const name = state('')                       // State<string>  const picked = state<string | null>(null)    // without <…> this would be State<null>  const drafts = state<Draft[]>([])            // without <…> this would be State<never[]>  return { name, picked, drafts }}

Writing the same value does nothing

A write compares the new value with the old one using Object.is. If they're the same, nothing happens: no reader runs, nothing on the page is touched.

const size = state('small')size.value = 'small'   // same string: nothing happenssize.value = 'large'   // different: readers update

For numbers and strings that's what you'd expect. For objects and arrays it means you must give the box a new object for a change to count. Changing a property inside the object the box already holds is invisible to it. That's the subject of Updating objects and arrays.

Giving a component several boxes

A component can have as many boxes as it needs. The gallery above has two: index for which picture, and showMore for whether the details are open:

const index = state(0)const showMore = state(false)

They change for different reasons, so they're separate. Pressing Next writes index; only what reads index updates. Pressing Show details writes showMore; only the details update.

When two values always change together, one box holding an object can be clearer:

const position = state({ x: 0, y: 0 })   // a pointer position: x and y move together

Choosing the state structure has the guidelines. And a value you can work out from other boxes isn't state at all: make it 0 and it can never go stale.

State is per component instance

Each place you use a component runs its function once, so each one makes its own boxes. Two counters are two counters:

Pressing +1 on Coffee writes Coffee's box. Tea's box is a different object, made by a different run of the same function, and doesn't change.

State is also private. The parent of a Counter can't read or write the count inside it; the count belongs to that Counter. When two components need the same value, you move the box up to their common parent and pass it down, or share it app-wide:

• Sharing state between components moves a box up and passes .value down.
• Writing to a parent with bind: lets a child write a box its parent owns.
• App-wide state with defineState makes a named scope of boxes any component can import.

Names in the dev tools

In a development build, the compiler gives each box a name from where it was made: const index = state(0) in Gallery is called Gallery.index. That's the name you see in the reactive graph (weft browser snapshot, the dev overlay, and graph() from @weft-js/core/devtools), and the name an AI agent sees through weft mcp. You don't write anything for it.

A box made inside a helper function rather than straight in a component has no such name. name(box, 'label') from @weft-js/core gives it one, and returns the box so you can wrap the call:

import { name, state } from '@weft-js/core'export function makeToggle(label: string) {  return name(state(false), `toggle.${label}`)}

In a production build name does nothing.

Recap

• A plain variable doesn't keep a change on the page: the body ran once. Make it state.
• state(initial) makes a box. Read and write .value, in handlers and in JSX alike (W015 without it).
• Reading .value subscribes; writing it updates exactly the readers. The component doesn't run again.
• A write that is Object.is the old value does nothing, so objects and arrays need a new value to count as changed.
• A component can have many boxes. Each instance has its own, and they're private to it.
• Compared with useState: one name instead of two, no snapshot, no hook rules, no re-render.

Try it