`query`

Find elements in the document.

The query functions lets you search your document for elements of a particular type or with a particular label.

To use it, you first need to retrieve the current document location with the locate function. You can then decide whether you want to find all elements, just the ones before that location, or just the ones after it.

Finding elements

In the example below, we create a custom page header that displays the text "Typst Academy" in small capitals and the current section title. On the first page, the section title is omitted because the header is before the first section heading.

To realize this layout, we call locate and then query for all headings after the current location. The function we pass to locate is called twice in this case: Once per page.

On the first page the query for all headings before the current location yields an empty array: There are no previous headings. We check for this case and and just display "Typst Academy".
For the second page, we retrieve the last element from the query's result. This is the latest heading before the current position and as such, it is the heading of the section we are currently in. We access its content through the body field and display it alongside "Typst Academy".

#set page(header: locate(loc => {
  let elems = query(
    selector(heading).before(loc),
    loc,
  )
  let academy = smallcaps[
    Typst Academy
  ]
  if elems == () {
    align(right, academy)
  } else {
    let body = elems.last().body
    academy + h(1fr) + emph(body)
  }
}))

= Introduction
#lorem(23)

= Background
#lorem(30)

= Analysis
#lorem(15)

A word of caution

To resolve all your queries, Typst evaluates and layouts parts of the document multiple times. However, there is no guarantee that your queries can actually be completely resolved. If you aren't careful a query can affect itself—leading to a result that never stabilizes.

In the example below, we query for all headings in the document. We then generate as many headings. In the beginning, there's just one heading, titled Real. Thus, count is 1 and one Fake heading is generated. Typst sees that the query's result has changed and processes it again. This time, count is 2 and two Fake headings are generated. This goes on and on. As we can see, the output has five headings. This is because Typst simply gives up after five attempts.

In general, you should try not to write queries that affect themselves. The same words of caution also apply to other introspection features like counters and state.

= Real
#locate(loc => {
  let elems = query(heading, loc)
  let count = elems.len()
  count * [= Fake]
})

Migration Hints

The before and after arguments have been removed in version 0.3.0. You can now use flexible selector combinator methods instead. For example, query(heading, before: loc) becomes query(heading.before(loc), loc). Please refer to the selector documentation for more details.

Parameters

query(

label function selector,location,

) -> array

`target`
label or function or selector
RequiredPositional

Can be an element function like a heading or figure, a <label> or a more complex selector like heading.where(level: 1).

Currently, only a subset of element functions is supported. Aside from headings and figures, this includes equations, references and all elements with an explicit label. As a result, you can query for e.g. strong elements, but you will find only those that have an explicit label attached to them. This limitation will be resolved in the future.

`location`
location
RequiredPositional

Can be any location. Why is it required then? As noted before, Typst has to evaluate parts of your code multiple times to determine the values of all state. By only allowing this function within locate calls, the amount of code that can depend on the query's result is reduced. If you could call it directly at the top level of a module, the evaluation of the whole module and its exports could depend on the query's result.

OutlinePrevious page

ReferenceNext page

query