{"route":"/en-US-v0.14.1/reference/introspection/state/","title":"State","description":"Documentation for the State type.","part":null,"outline":[{"id":"summary","name":"Summary","children":[]},{"id":"state-and-markup","name":"State And Markup","children":[]},{"id":"state-in-typst","name":"State In Typst","children":[]},{"id":"time-travel","name":"Time Travel","children":[]},{"id":"caution","name":"Caution","children":[]},{"id":"constructor","name":"Constructor","children":[{"id":"constructor-key","name":"key","children":[]},{"id":"constructor-init","name":"init","children":[]}]},{"id":"definitions","name":"Definitions","children":[{"id":"definitions-get","name":"Get","children":[]},{"id":"definitions-at","name":"At","children":[{"id":"definitions-at-selector","name":"selector","children":[]}]},{"id":"definitions-final","name":"Final","children":[]},{"id":"definitions-update","name":"Update","children":[{"id":"definitions-update-update","name":"update","children":[]}]}]}],"body":{"kind":"type","content":{"name":"state","title":"State","keywords":[],"oneliner":"Manages stateful parts of your document.","details":"

Manages stateful parts of your document.

\n

Let's say you have some computations in your document and want to remember\nthe result of your last computation to use it in the next one. You might try\nsomething similar to the code below and expect it to output 10, 13, 26, and\n21. However this does not work in Typst. If you test this code, you will\nsee that Typst complains with the following error message: Variables from\noutside the function are read-only and cannot be modified.

\n
// This doesn't work!\n#let star = 0\n#let compute(expr) = {\n  star = eval(\n    expr.replace("⭐", str(star))\n  )\n  [New value is #star.]\n}\n\n#compute("10") \\\n#compute("⭐ + 3") \\\n#compute("⭐ * 2") \\\n#compute("⭐ - 5")\n
\n

State and document markup

\n

Why does it do that? Because, in general, this kind of computation with side\neffects is problematic in document markup and Typst is upfront about that.\nFor the results to make sense, the computation must proceed in the same\norder in which the results will be laid out in the document. In our simple\nexample, that's the case, but in general it might not be.

\n

Let's look at a slightly different, but similar kind of state: The heading\nnumbering. We want to increase the heading counter at each heading. Easy\nenough, right? Just add one. Well, it's not that simple. Consider the\nfollowing example:

\n
#set heading(numbering: "1.")\n#let template(body) = [\n  = Outline\n  ...\n  #body\n]\n\n#show: template\n\n= Introduction\n...\n
\"Preview\"
\n

Here, Typst first processes the body of the document after the show rule,\nsees the Introduction heading, then passes the resulting content to the\ntemplate function and only then sees the Outline. Just counting up would\nnumber the Introduction with 1 and the Outline with 2.

\n

Managing state in Typst

\n

So what do we do instead? We use Typst's state management system. Calling\nthe state function with an identifying string key and an optional initial\nvalue gives you a state value which exposes a few functions. The two most\nimportant ones are get and update:

\n\n

Our initial example would now look like this:

\n
#let star = state("star", 0)\n#let compute(expr) = {\n  star.update(old =>\n    eval(expr.replace("⭐", str(old)))\n  )\n  [New value is #context star.get().]\n}\n\n#compute("10") \\\n#compute("⭐ + 3") \\\n#compute("⭐ * 2") \\\n#compute("⭐ - 5")\n
\"Preview\"
\n

State managed by Typst is always updated in layout order, not in evaluation\norder. The update method returns content and its effect occurs at the\nposition where the returned content is inserted into the document.

\n

As a result, we can now also store some of the computations in variables,\nbut they still show the correct results:

\n
...\n\n#let more = [\n  #compute("⭐ * 2") \\\n  #compute("⭐ - 5")\n]\n\n#compute("10") \\\n#compute("⭐ + 3") \\\n#more\n
\"Preview\"
\n

This example is of course a bit silly, but in practice this is often exactly\nwhat you want! A good example are heading counters, which is why Typst's\ncounting system is very similar to its state system.

\n

Time Travel

\n

By using Typst's state management system you also get time travel\ncapabilities! We can find out what the value of the state will be at any\nposition in the document from anywhere else. In particular, the at method\ngives us the value of the state at any particular location and the final\nmethods gives us the value of the state at the end of the document.

\n
...\n\nValue at `<here>` is\n#context star.at(<here>)\n\n#compute("10") \\\n#compute("⭐ + 3") \\\n*Here.* <here> \\\n#compute("⭐ * 2") \\\n#compute("⭐ - 5")\n
\"Preview\"
\n

A word of caution

\n

To resolve the values of all states, Typst evaluates parts of your code\nmultiple times. However, there is no guarantee that your state manipulation\ncan actually be completely resolved.

\n

For instance, if you generate state updates depending on the final value of\na state, the results might never converge. The example below illustrates\nthis. We initialize our state with 1 and then update it to its own final\nvalue plus 1. So it should be 2, but then its final value is 2, so it\nshould be 3, and so on. This example displays a finite value because Typst\nsimply gives up after a few attempts.

\n
// This is bad!\n#let x = state("key", 1)\n#context x.update(x.final() + 1)\n#context x.get()\n
\"Preview\"
\n

In general, you should try not to generate state updates from within context\nexpressions. If possible, try to express your updates as non-contextual\nvalues or functions that compute the new value from the previous value.\nSometimes, it cannot be helped, but in those cases it is up to you to ensure\nthat the result converges.

","constructor":{"path":[],"name":"state","title":"Construct","keywords":[],"oneliner":"Create a new state identified by a key.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Create a new state identified by a key.

"}],"self":false,"params":[{"name":"key","details":[{"kind":"html","content":"

The key that identifies this state.

\n

Any updates to the state will be identified with\nthe string key. If you construct multiple states with the same\nkey, then updating any one will affect all of them.

"}],"types":["str"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false},{"name":"init","details":[{"kind":"html","content":"

The initial value of the state.

\n

If you construct multiple states with the same key but different\ninit values, they will each use their own initial value but share\nupdates. Specifically, the value of a state at some location in the\ndocument will be computed from that state's initial value and all\npreceding updates for the state's key.

"},{"kind":"example","content":{"body":"
#let banana = state("key", "🍌")\n#let broccoli = state("key", "🥦")\n\n#banana.update(it => it + "😋")\n\n#context [\n  - #state("key", "🍎").get()\n  - #banana.get()\n  - #broccoli.get()\n]\n
\"Preview\"
","title":null}}],"types":["any"],"strings":[],"default":"none","positional":true,"named":false,"required":false,"variadic":false,"settable":false}],"returns":["state"],"scope":[]},"scope":[{"path":["state"],"name":"get","title":"Get","keywords":[],"oneliner":"Retrieves the value of the state at the current location.","element":false,"contextual":true,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Retrieves the value of the state at the current location.

\n

This is equivalent to state.at(here()).

"}],"self":true,"params":[],"returns":["any"],"scope":[]},{"path":["state"],"name":"at","title":"At","keywords":[],"oneliner":"Retrieves the value of the state at the given selector's unique match.","element":false,"contextual":true,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Retrieves the value of the state at the given selector's unique match.

\n

The selector must match exactly one element in the document. The most\nuseful kinds of selectors for this are labels and\nlocations.

"}],"self":true,"params":[{"name":"selector","details":[{"kind":"html","content":"

The place at which the state's value should be retrieved.

"}],"types":["label","selector","location","function"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["any"],"scope":[]},{"path":["state"],"name":"final","title":"Final","keywords":[],"oneliner":"Retrieves the value of the state at the end of the document.","element":false,"contextual":true,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Retrieves the value of the state at the end of the document.

"}],"self":true,"params":[],"returns":["any"],"scope":[]},{"path":["state"],"name":"update","title":"Update","keywords":[],"oneliner":"Updates the value of the state.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Updates the value of the state.

\n

Returns an invisible piece of content that must be inserted into the\ndocument to take effect. This invisible content tells Typst that the\nspecified update should take place wherever the content is inserted into\nthe document.

\n

State is a part of your document and runs like a thread embedded in the\ndocument content. The value of a state is the result of all state\nupdates that happened in the document up until that point.

\n

That's why state.update returns an invisible sliver of content that\nyou need to return and include in the document — a state update that is\nnot "placed" in the document does not happen, and "when" it happens is\ndetermined by where you place it. That's also why you need context to\nread state: You need to use the current document position to know where\non the state's "thread" you are.

\n

Storing a state update in a variable (e.g.\nlet my-update = state("key").update(c => c * 2)) will have no effect\nby itself. Only once you insert the variable #my-update somewhere\ninto the document content, the update will take effect — at the position\nwhere it was inserted. You can also use #my-update multiple times at\ndifferent positions. Then, the update will take effect multiple times as\nwell.

\n

In contrast to get, at, and\nfinal, this function does not require context. This\nis because, to create the state update, we do not need to know where in\nthe document we are. We only need this information to resolve the\nstate's value.

"}],"self":true,"params":[{"name":"update","details":[{"kind":"html","content":"

A value to update to or a function to update with.

\n\n

When updating the state based on its previous value, you should\nprefer the function form instead of retrieving the previous value\nfrom the context. This allows the compiler to resolve\nthe final state efficiently, minimizing the number of\nlayout iterations required.

\n

In the following example, fill.update(f => not f) will paint odd\nitems in the bullet list as expected. However, if it's\nreplaced with context fill.update(not fill.get()), then layout\nwill not converge within 5 attempts, as each update will take one\nadditional iteration to propagate.

"},{"kind":"example","content":{"body":"
#let fill = state("fill", false)\n\n#show list.item: it => {\n  fill.update(f => not f)\n  context {\n    set text(fill: fuchsia) if fill.get()\n    it\n  }\n}\n\n#lorem(5).split().map(list.item).join()\n
\"Preview\"
","title":null}}],"types":["any","function"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["content"],"scope":[]}]}}}