Typst References
Add a label with <label>. Reference with @label. Typst auto-fills "Section 2", "Figure 1", "Equation (3)" depending on the element type.
The basics
= Methods <methods>
This section describes our methods.
= Results
As discussed in @methods, our approach...
#figure(
image("architecture.png"),
caption: [System architecture.]
) <arch>
Figure @arch shows the architecture.
#set math.equation(numbering: "(1)")
$ E = m c^2 $ <einstein>
Equation @einstein expresses the principle.Labels and references work for any element
| Element | Auto-displayed as |
|---|---|
| Heading | "Section 2" (with numbering pattern) |
| Figure | "Figure 1" |
| Table | "Table 1" |
| Equation | "(1)" (or whatever numbering you set) |
| Custom block with label | Just the link, no auto-text (customize via #show) |
Customize the displayed text
// Always use full word "Section" instead of "Sec."
#show ref: it => {
let el = it.element
if el != none and el.func() == heading {
[Section #counter(heading).at(el.location()).at(0)]
} else {
it // default for other types
}
}
= Methods <methods>
See @methods. // renders as "Section 2"Reference with custom display text
= Methods <methods>
// @methods renders default: "Section 2"
// For custom text:
#link(<methods>)[the methods we describe below]
// Or for hyperlinked custom text + auto number:
See the methods (see @methods for details).Common mistakes
- Putting the label BEFORE the element. Labels go AFTER:
= Heading <label>. Before puts the label on the previous element. - Duplicate labels. Each label must be unique. Typst errors on collision.
- Using @ for external URLs. @ is for internal labels only. External:
#link("..."). - Forgetting numbering for equations/sections. Without
#set math.equation(numbering: ...)or#set heading(numbering: ...), references show without numbers.
TypeTeX is a free in-browser Typst editor — write a reference, see the auto-rendered "Figure 1" or "Section 2" instantly.
Try TypeTeX freeFrequently Asked Questions
Add a label after the element with <label>: '= Methods <methods>' or '#figure(...) <fig:arch>'. Then reference with @methods or @fig:arch in body text. Typst auto-fills 'Section 2' or 'Figure 1' depending on the element kind.
@label is the inline syntax — most common, reads like a citation. #ref(<label>) is the explicit function call, useful in code blocks or when constructing references programmatically. Both produce identical output.
Use a #show rule: #show ref: it => { ... }. Inside, you can access it.target (the labeled element). Example: #show ref: it => link(it.target.location(), [Custom text for #it]). Most users don't need to customize — Typst's default rendering ('Figure 1', 'Section 2') is usually right.
Yes. Place <label> after any block: a paragraph, a list, an equation. Reference with @label. Typst stores labels in a global namespace — they must be unique across the document.
Number equations with #set math.equation(numbering: "(1)"). Then label and reference: '$ E = m c^2 $ <einstein>'. Body: 'See @einstein for the equation.' Typst inserts '(1)' automatically.
External: #link("https://example.com")[link text]. Internal: @label or #ref(<label>). The @ syntax is for internal labels; #link is for any URL (internal or external). Don't confuse them.
Use the location of the labeled element: #context query(<my-label>).first().location().page(). Returns the page number. Useful for 'See page N' style references. Wrap in #context because location queries need evaluation context.
Typst's @label is single-character, automatic context detection (knows it's a section vs figure vs equation), and includes hyperlinks by default with hyperref-style linking. LaTeX needs \ref{name} (numeric) or \autoref{name} (with hyperref) for similar functionality. Typst is dramatically simpler.