{"route":"/en-US-v0.13.1/reference/context/","title":"Context","description":"How to deal with content that reacts to its location in the document.\n","part":null,"outline":[{"id":"style-context","name":"Style context","children":[]},{"id":"location-context","name":"Location context","children":[]},{"id":"nested-contexts","name":"Nested contexts","children":[]},{"id":"compiler-iterations","name":"Compiler iterations","children":[]}],"body":{"kind":"html","content":"

Context

\n

Sometimes, we want to create content that reacts to its location in the\ndocument. This could be a localized phrase that depends on the configured text\nlanguage or something as simple as a heading number which prints the right\nvalue based on how many headings came before it. However, Typst code isn't\ndirectly aware of its location in the document. Some code at the beginning of\nthe source text could yield content that ends up at the back of the document.

\n

To produce content that is reactive to its surroundings, we must thus\nspecifically instruct Typst: We do this with the context keyword, which\nprecedes an expression and ensures that it is computed with knowledge of its\nenvironment. In return, the context expression itself ends up opaque. We cannot\ndirectly access whatever results from it in our code, precisely because it is\ncontextual: There is no one correct result, there may be multiple results in\ndifferent places of the document. For this reason, everything that depends on\nthe contextual data must happen inside of the context expression.

\n

Aside from explicit context expressions, context is also established implicitly\nin some places that are also aware of their location in the document:\nShow rules provide context1 and numberings in the\noutline, for instance, also provide the proper context to resolve counters.

\n

Style context

\n

With set rules, we can adjust style properties for parts or the whole of our\ndocument. We cannot access these without a known context, as they may change\nthroughout the course of the document. When context is available, we can\nretrieve them simply by accessing them as fields on the respective element\nfunction.

\n
#set text(lang: "de")\n#context text.lang\n
\"Preview\"
\n

As explained above, a context expression is reactive to the different\nenvironments it is placed into. In the example below, we create a single context\nexpression, store it in the value variable and use it multiple times. Each use\nproperly reacts to the current surroundings.

\n
#let value = context text.lang\n#value\n\n#set text(lang: "de")\n#value\n\n#set text(lang: "fr")\n#value\n
\"Preview\"
\n

Crucially, upon creation, value becomes opaque content that we cannot peek\ninto. It can only be resolved when placed somewhere because only then the\ncontext is known. The body of a context expression may be evaluated zero, one,\nor multiple times, depending on how many different places it is put into.

\n

Location context

\n

We've already seen that context gives us access to set rule values. But it can\ndo more: It also lets us know where in the document we currently are, relative\nto other elements, and absolutely on the pages. We can use this information to\ncreate very flexible interactions between different document parts. This\nunderpins features like heading numbering, the table of contents, or page\nheaders dependent on section headings.

\n

Some functions like counter.get implicitly access the current\nlocation. In the example below, we want to retrieve the value of the heading\ncounter. Since it changes throughout the document, we need to first enter a\ncontext expression. Then, we use get to retrieve the counter's current value.\nThis function accesses the current location from the context to resolve the\ncounter value. Counters have multiple levels and get returns an array with the\nresolved numbers. Thus, we get the following result:

\n
#set heading(numbering: "1.")\n\n= Introduction\n#lorem(5)\n\n#context counter(heading).get()\n\n= Background\n#lorem(5)\n\n#context counter(heading).get()\n
\"Preview\"
\n

For more flexibility, we can also use the here function to directly extract\nthe current location from the context. The example below\ndemonstrates this:

\n\n
#set heading(numbering: "1.")\n\n= Introduction <intro>\n#lorem(5)\n\n= Background <back>\n#lorem(5)\n\n#context [\n  #counter(heading).get() \\\n  #counter(heading).at(here()) \\\n  #counter(heading).at(<intro>)\n]\n
\"Preview\"
\n

As mentioned before, we can also use context to get the physical position of\nelements on the pages. We do this with the locate function, which works\nsimilarly to counter.at: It takes a location or other selector that resolves\nto a unique element (could also be a label) and returns the position on the\npages for that element.

\n
Background is at: \\\n#context locate(<back>).position()\n\n= Introduction <intro>\n#lorem(5)\n#pagebreak()\n\n= Background <back>\n#lorem(5)\n
\"Preview\"
\n

There are other functions that make use of the location context, most\nprominently query. Take a look at the\nintrospection category for more details on those.

\n

Nested contexts

\n

Context is also accessible from within function calls nested in context blocks.\nIn the example below, foo itself becomes a contextual function, just like\nto-absolute is.

\n
#let foo() = 1em.to-absolute()\n#context {\n  foo() == text.size\n}\n
\"Preview\"
\n

Context blocks can be nested. Contextual code will then always access the\ninnermost context. The example below demonstrates this: The first text.lang\nwill access the outer context block's styles and as such, it will not\nsee the effect of set text(lang: "fr"). The nested context block around the\nsecond text.lang, however, starts after the set rule and will thus show\nits effect.

\n
#set text(lang: "de")\n#context [\n  #set text(lang: "fr")\n  #text.lang \\\n  #context text.lang\n]\n
\"Preview\"
\n

You might wonder why Typst ignores the French set rule when computing the first\ntext.lang in the example above. The reason is that, in the general case, Typst\ncannot know all the styles that will apply as set rules can be applied to\ncontent after it has been constructed. Below, text.lang is already computed\nwhen the template function is applied. As such, it cannot possibly be aware of\nthe language change to French in the template.

\n
#let template(body) = {\n  set text(lang: "fr")\n  upper(body)\n}\n\n#set text(lang: "de")\n#context [\n  #show: template\n  #text.lang \\\n  #context text.lang\n]\n
\"Preview\"
\n

The second text.lang, however, does react to the language change because\nevaluation of its surrounding context block is deferred until the styles for it\nare known. This illustrates the importance of picking the right insertion point for a context to get access to precisely the right styles.

\n

The same also holds true for the location context. Below, the first\nc.display() call will access the outer context block and will thus not see\nthe effect of c.update(2) while the second c.display() accesses the inner context and will thus see it.

\n
#let c = counter("mycounter")\n#c.update(1)\n#context [\n  #c.update(2)\n  #c.display() \\\n  #context c.display()\n]\n
\"Preview\"
\n

Compiler iterations

\n

To resolve contextual interactions, the Typst compiler processes your document\nmultiple times. For instance, to resolve a locate call, Typst first provides a\nplaceholder position, layouts your document and then recompiles with the known\nposition from the finished layout. The same approach is taken to resolve\ncounters, states, and queries. In certain cases, Typst may even need more than\ntwo iterations to resolve everything. While that's sometimes a necessity, it may\nalso be a sign of misuse of contextual functions (e.g. of\nstate). If Typst cannot resolve everything within five\nattempts, it will stop and output the warning "layout did not converge within 5\nattempts."

\n

A very careful reader might have noticed that not all of the functions presented\nabove actually make use of the current location. While\ncounter(heading).get() definitely depends on it,\ncounter(heading).at(<intro>), for instance, does not. However, it still\nrequires context. While its value is always the same within one compilation\niteration, it may change over the course of multiple compiler iterations. If one\ncould call it directly at the top level of a module, the whole module and its\nexports could change over the course of multiple compiler iterations, which\nwould not be desirable.

\n
1\n

Currently, all show rules provide styling context, but only show rules on\nlocatable elements provide a location context.

\n
"}}