Tutorial
The language
State and reactivity
A state is a signal, and only what reads it updates: no tree re-renders, no subscriptions to manage.
This chapter covers state and reactivity in WebFluent. A state is a value the page can change. Anything that reads it — a text, an attribute, a derived value, an effect, a style splice — updates when it changes, and nothing else does. This is fine-grained reactivity: there is no re-render of a component tree, and you never subscribe or unsubscribe by hand.
In this chapter:
state,derivedandeffect— the three kinds of reactive value- actions and
letlocals — the code that changes state persist, timers and element handles- how the runtime cleans up after a page, a branch or a list item
- the browser's own values:
viewport,query,nowand the rest - where a name is looked up, and the mistakes people make
state
You declare a state at the top of a page, component or store body, with an initial value. This counter shows the whole idea — one state, a text that reads it, and a button that writes it:
page Counter(path: "/", title: "Counter", description: "A state, read and written.") {
state count = 0 // inferred: Number
state name: String = "Sam" // declared
state items: [String] = [] // a list of strings
state selected: String? = null // may be null
state user = { name: "Sam", tags: ["admin"] } // a map literal: its fields are its type
Heading("Counter").h1
Text("{name} has clicked {count} times")
Button("+1") { on click { count = count + 1 } }
}
Each click sets count, and only the Text that reads it changes.
Note
Coming from React? useState returns a value and a setter, and a change runs the whole component again. A state is assigned directly, count = count + 1, and the body never runs again: only what reads count updates. A value that should follow a prop or a state is a derived. See Coming from React.
The type of a state is read off its initial value, or written after a colon. Types has the type language. Assigning a value of another type is an error (T01).
You write state only in an imperative block — a handler, an action or an effect. You can:
- assign it:
count = count + 1 - change a place inside it:
user.name = "Ann",items[0] = "Pen" - call a method that changes it:
items.push("Pen"),items.sort()
A change inside a value gives the state a new copy with that place changed, so everything that reads it repaints, and a persist value is written.
The static paint — the HTML the build pre-renders for a page — seeds every state with its initial value, so a pre-rendered page shows what the first paint in the browser would.
derived
A derived value is computed from state, and computed again when any state it read changes. This cart works out its subtotal, total and whether it is empty:
page Cart(path: "/", title: "Cart", description: "Totals worked out from state.") {
state items = [{ name: "Pen", price: 2.5, qty: 4 }, { name: "Pad", price: 6, qty: 1 }]
state taxRate = 0.2
derived subtotal = items.reduce((sum, i) => sum + i.price * i.qty, 0)
derived total = subtotal * (1 + taxRate)
derived empty = items.length == 0
Heading("Your cart").h1
Text("Subtotal: {format(subtotal, .currency)}")
Text("Total: {format(total, .currency)}")
if empty { Text("Your cart is empty.").muted }
}
The rules:
- A derived value may read state, other derived values and the browser's values, and may call an action that returns a value.
- It is never assigned to (
X01), and an action it calls may not assign state (X04). - The static paint seeds it from the initial state.
effect
An effect runs once, then again whenever a state it read changes. Its cleanup { } block runs before the next run, and when the page — or the branch the effect lives in — leaves:
page Watch(path: "/", title: "Watch", description: "Effects that follow a search.") {
state search = ""
effect {
log("search is now {search}")
}
effect {
document.title = "Search: {search}"
cleanup { document.title = "Search" }
}
Heading("Watch").h1
Input(bind: search, placeholder: "Search")
}
Use an effect for the world outside the page: the document title, a third-party widget, a subscription. Keep computation in derived.
Warning
An effect that writes what it reads — effect { n = n + 1 } — starts its own next run and never settles. The compiler refuses it (X02). Compute the value with derived instead.
Actions and locals
An action is a named function of a page, component or store. Its body is an imperative block: assignments, let locals, calls, if, for, try, return and await. This to-do list adds, removes and loads items with three actions:
type TodoList { todos: [String] }
page Todos(path: "/", title: "To-dos", description: "Actions that change a list.") {
state items: [String] = []
state draft = ""
action add() {
let text = draft.trim()
if text == "" { return }
items.push(text)
draft = ""
}
action remove(index: Number) {
items = items.filter((_, i) => i != index)
}
action load() -> ! {
let list: TodoList = try await http.get("/api/todos")
items = list.todos
}
Heading("To-dos").h1
Input(bind: draft, placeholder: "What needs doing?") { on keydown(e) { if e.key == "Enter" { add() } } }
Button("Add").primary { on click { add() } }
for item, i in items {
Row { Text(item) IconButton(icon: "trash", label: "Remove") { on click { remove(i) } } }
}
}
What an action's body can hold:
- Locals.
let x = …declares a local of the action or handler.let { a, b } = mandlet [x, y] = ldestructure a map and a list. await. Using it makes the action asynchronous, andname.pendingistruewhile a call of it runs (Forms).- Loops.
for item in list { },for item, i in list { }andfor n in 1..=10 { }. - Errors. A request's answer is a result:
trygives its value or passes the failure up, in an action that says what it fails with (-> !here), andmatchhandles each case where the call is made (Fetching data).try { } catch e { }guards a call into a script that may throw. return.returnleaves the action;return xleaves with a value.
A let is the action's own. After let list = items, list.push(x) changes list and leaves items as it was; assign it back with items = list, or write items.push(x), which gives the state a new list.
You call a page's action by name, add(), and a store's through the store, Todos.add().
persist
persist declares a state kept in the browser's storage across visits. It is read back on the next visit and written on every change. These two preferences survive a reload:
page Prefs(path: "/", title: "Preferences", description: "Settings kept across visits.") {
persist scheme = "light"
persist perPage = 20
Heading("Preferences").h1
Select(bind: scheme, label: "Theme") {
Select.Option("Light", value: "light")
Select.Option("Dark", value: "dark")
}
Slider(bind: perPage, min: 10, max: 100, step: 10, label: "Rows per page")
}
How it behaves:
- The storage key is the owner's name and the state's (
Prefs.scheme), so a page and a store may each have a value of the same name. - It works in a store too, where every page shares it.
- When storage is blocked or full, the value falls back to its initial value.
- A block after the declaration can say which storage to use, give a version with migrations, and choose whether to follow other tabs. That block and the rest of the policy are in Stores.
Timers
every(ms) { } repeats, and after(ms) { } fires once. The interval is a number of milliseconds or a duration: every(5.seconds), after(2.minutes). This page counts the seconds it has been open and hides a welcome message after three:
page Clock(path: "/", title: "Clock", description: "A timer and a one-off delay.") {
state seconds = 0
state toast: String? = "Welcome"
every(1000) { seconds = seconds + 1 }
after(3000) { toast = null }
Heading("Clock").h1
Text("{seconds}s on this page")
if let message = toast { Alert(message).info }
}
Both stop when what declared them leaves the page: a branch that closes, a list item that is removed, a route that changes.
Automatic clean-up
Everything a body creates — effects, timers, listeners, element handles — belongs to the scope it was created in: the page, branch, list item, match arm or slot whose nodes it sits among. When that scope's nodes leave, the runtime disposes of what it created:
- an
ifbranch turns false, an item drops out of afor, amatcharm changes, or the route changes; - intervals are cleared, effects stop running, and
cleanup { }blocks run.
You never unsubscribe by hand.
Element handles
ref: name on an element gives you a handle: a name that reads as the element itself. Here a button and the / key both put the cursor in the search box:
page Search(path: "/", title: "Search", description: "A handle on an input.") {
state q = ""
Heading("Search").h1
Input(bind: q, ref: box, placeholder: "Search")
Button("Focus the box") { on click { box.focus() } }
Button("Clear") { on click { q = "" box.focus() } }
on key("/") { box.focus() }
}
The ref: declares the name; you do not declare it anywhere else. Anything the element has is there: box.value, box.scrollIntoView().
A handle is filled once the element exists, so set-up code at the top of the body cannot use it yet. Read it in a handler, an effect or after(0) { }.
The browser as values
Some names are always in scope and kept current by the runtime, so a page reads the browser the way it reads its own state:
| Name | Is | Updates when |
|---|---|---|
|
|
|
a breakpoint is crossed (through |
|
|
the URL's query string as a map: |
the URL changes |
|
|
the URL's |
the URL changes |
|
|
|
|
|
|
a |
the clock ticks |
|
|
|
the connection changes |
|
|
|
a new build is installed |
|
|
the current locale and |
|
This page reads four of them:
page Where(path: "/", title: "Where", description: "The browser, read as values.") {
Heading("Where am I?").h1
Text(if viewport.md { "A wide window" } else { "A narrow window" })
derived tab = query.tab ?? "all"
Text("Tab: {tab}, section: {hash}")
Text("Theme: {theme}")
if !network.online { Alert("You are offline.").warning }
}
The rules:
- The breakpoints are the
screen-sm…screen-xldesign tokens: 640, 768, 1024 and 1280px unless a theme moves them. - They are the language's names, so a
state, prop orconstof the same name is an error (E118). - Copy one into a
stateand you keep the value it had when the page opened:state clock = now(every: 1.seconds)never ticks (X06). Read it where it is shown, or in aderived. - The static paint does not know them, so what depends on them is drawn once the page is live. For layout, prefer responsive values, which are right in the first paint.
Where values come from, in order
When a body reads a name, the nearest declaration wins. The compiler looks in this order, innermost first:
- A
letlocal, a lambda's parameter or a caught error, inside its block. - Loop variables and arm bindings (
if let, amatcharm), inside their block. - Route parameters and props (
slug,_ label). state,persist,derived,resourceand actions of the body. A body member may not share a name with a parameter or a prop (E102).- A
used store's members, always through the store's name (Cart.total). - Constants,
dataandimagedeclarations,env.X, and the browser's values above. - Browser globals:
window,document,localStorage,JSON,Math,Date,setTimeout,console,navigator,location. (A request ishttp.get(…); the browser's ownfetchiswindow.fetch.)
So with state name = "outer", for name in items by name { Text(name) } shows each item, and a const name is hidden by both.
Summary
| You write | It is | Section |
|---|---|---|
|
|
a value the page changes; its readers update | |
|
|
a value computed from state, never assigned | |
|
|
code that runs when what it read changes | |
|
|
a named function that changes state | |
|
|
a local of an action or handler | |
|
|
a state kept across visits | |
|
|
a repeating timer and a one-off delay | |
|
|
a handle on an element | |
|
|
the browser, read as values |
Grammar and Built-in functions are the reference for each.
Quiz
Check your understanding
A page shows Heading("Counter") and Text("{count}"). A click runs count = count + 1. What runs again?
Check your understanding
items is a state. Which total stays equal to the sum of items as items are added?
Check your understanding
Which of these clocks ticks every second?
Common mistakes
A state that copies now once. A state takes its initial value when the page opens and keeps it, so a clock or an "… ago" worked out from it never moves:
page Feed(path: "/", title: "Feed", description: "When this was posted.") {
state posted = @2026-03-14T09:30:00Z
state clock = now(every: 1.seconds)
Heading("Feed").h1
Text("Posted {posted.until(clock).minutes()} minutes ago")
}
Declare it derived clock = now(every: 1.seconds). The same holds for viewport, query, hash, theme, network and update (X06).
An effect that writes what it reads. Each run changes visits, which starts the next run, so the page never settles:
page Visits(path: "/", title: "Visits", description: "A count that runs away.") {
state visits = 0
effect { visits = visits + 1 }
Heading("Visits").h1
Text("{visits} visits")
}
Change the state in a handler or an action, or work the value out with derived (X02).
Assigning a derived value. A derived is worked out from what it reads, so nothing may set it:
page Cart(path: "/", title: "Cart", description: "A total you cannot set.") {
state items = [2.5, 6]
derived total = items.sum()
Heading("Cart").h1
Text("Total: {total}")
Button("Clear") { on click { total = 0 } }
}
Change what it reads instead, items = [], and total follows (X01).
What you learned
-
Declare a
stateand change it from a handler or an action -
Work a value out with
derivedinstead of keeping a second state in step -
Reach outside the page with an
effectand itscleanup -
Keep a value across visits with
persist, and run timers witheveryandafter -
Read
viewport,query,nowand the browser's other values as live values