{"route":"/en-US-v0.13.1/reference/model/ref/","title":"Reference","description":"Documentation for the `ref` function.","part":null,"outline":[{"id":"summary","name":"Summary","children":[]},{"id":"example","name":"Example","children":[]},{"id":"syntax","name":"Syntax","children":[]},{"id":"customization","name":"Customization","children":[]},{"id":"parameters","name":"Parameters","children":[{"id":"parameters-target","name":"target","children":[]},{"id":"parameters-supplement","name":"supplement","children":[]},{"id":"parameters-form","name":"form","children":[]}]}],"body":{"kind":"func","content":{"path":[],"name":"ref","title":"Reference","keywords":[],"oneliner":"A reference to a label or bibliography.","element":true,"contextual":false,"deprecation":null,"details":"

A reference to a label or bibliography.

\n

Takes a label and cross-references it. There are two kind of references,\ndetermined by its form: "normal" and "page".

\n

The default, a "normal" reference, produces a textual reference to a\nlabel. For example, a reference to a heading will yield an appropriate\nstring such as "Section 1" for a reference to the first heading. The\nreferences are also links to the respective element. Reference syntax can\nalso be used to cite from a bibliography.

\n

As the default form requires a supplement and numbering, the label must be\nattached to a referenceable element. Referenceable elements include\nheadings, figures, equations, and\nfootnotes. To create a custom referenceable element like a\ntheorem, you can create a figure of a custom kind and\nwrite a show rule for it. In the future, there might be a more direct way\nto define a custom referenceable element.

\n

If you just want to link to a labelled element and not get an automatic\ntextual reference, consider using the link function instead.

\n

A "page" reference produces a page reference to a label, displaying the\npage number at its location. You can use the\npage's supplement to modify the text before the page\nnumber. Unlike a "normal" reference, the label can be attached to any\nelement.

\n

Example

\n
#set page(numbering: "1")\n#set heading(numbering: "1.")\n#set math.equation(numbering: "(1)")\n\n= Introduction <intro>\nRecent developments in\ntypesetting software have\nrekindled hope in previously\nfrustrated researchers. @distress\nAs shown in @results (see\n#ref(<results>, form: "page")),\nwe ...\n\n= Results <results>\nWe discuss our approach in\ncomparison with others.\n\n== Performance <perf>\n@slow demonstrates what slow\nsoftware looks like.\n$ T(n) = O(2^n) $ <slow>\n\n#bibliography("works.bib")\n
\"Preview\"
\n

Syntax

\n

This function also has dedicated syntax: A "normal" reference to a\nlabel can be created by typing an @ followed by the name of the label\n(e.g. = Introduction <intro> can be referenced by typing @intro).

\n

To customize the supplement, add content in square brackets after the\nreference: @intro[Chapter].

\n

Customization

\n

If you write a show rule for references, you can access the referenced\nelement through the element field of the reference. The element may\nbe none even if it exists if Typst hasn't discovered it yet, so you\nalways need to handle that case in your code.

\n
#set heading(numbering: "1.")\n#set math.equation(numbering: "(1)")\n\n#show ref: it => {\n  let eq = math.equation\n  let el = it.element\n  if el != none and el.func() == eq {\n    // Override equation references.\n    link(el.location(),numbering(\n      el.numbering,\n      ..counter(eq).at(el.location())\n    ))\n  } else {\n    // Other references as usual.\n    it\n  }\n}\n\n= Beginnings <beginning>\nIn @beginning we prove @pythagoras.\n$ a^2 + b^2 = c^2 $ <pythagoras>\n
\"Preview\"
","example":null,"self":false,"params":[{"name":"target","details":"

The target label that should be referenced.

\n

Can be a label that is defined in the document or, if the\nform is set to "normal", an entry from the\nbibliography.

","example":null,"types":["label"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false},{"name":"supplement","details":"

A supplement for the reference.

\n

If the form is set to "normal":

\n\n

If the form is set to "page", then this is added\nbefore the page number of the label referenced.

\n

If a function is specified, it is passed the referenced element and\nshould return content.

","example":"
#set heading(numbering: "1.")\n#show ref.where(\n  form: "normal"\n): set ref(supplement: it => {\n  if it.func() == heading {\n    "Chapter"\n  } else {\n    "Thing"\n  }\n})\n\n= Introduction <intro>\nIn @intro, we see how to turn\nSections into Chapters. And\nin @intro[Part], it is done\nmanually.\n
\"Preview\"
","types":["none","auto","content","function"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"form","details":"

The kind of reference to produce.

","example":"
#set page(numbering: "1")\n\nHere <here> we are on\n#ref(<here>, form: "page").\n
\"Preview\"
","types":["str"],"strings":[{"string":"normal","details":"

Produces a textual reference to a label.

"},{"string":"page","details":"

Produces a page reference to a label.

"}],"default":""normal"","positional":false,"named":true,"required":false,"variadic":false,"settable":true}],"returns":["content"],"scope":[]}}}