Struct RefElem

pub struct RefElem {
    pub target: Label,
    /* private fields */
}

A reference to a label or bibliography.

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

The default, a {"normal"} reference, produces a textual reference to a label. For example, a reference to a heading will yield an appropriate string such as “Section 1” for a reference to the first heading. The references are also links to the respective element. Reference syntax can also be used to [cite] from a bibliography.

As the default form requires a supplement and numbering, the label must be attached to a referenceable element. Referenceable elements include headings, figures, equations, and footnotes. To create a custom referenceable element like a theorem, you can create a figure of a custom kind and write a show rule for it. In the future, there might be a more direct way to define a custom referenceable element.

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

A {"page"} reference produces a page reference to a label, displaying the page number at its location. You can use the page’s supplement to modify the text before the page number. Unlike a {"normal"} reference, the label can be attached to any element.

Example

#set page(numbering: "1")
#set heading(numbering: "1.")
#set math.equation(numbering: "(1)")

= Introduction <intro>
Recent developments in
typesetting software have
rekindled hope in previously
frustrated researchers. @distress
As shown in @results (see
#ref(<results>, form: "page")),
we ...

= Results <results>
We discuss our approach in
comparison with others.

== Performance <perf>
@slow demonstrates what slow
software looks like.
$ T(n) = O(2^n) $ <slow>

#bibliography("works.bib")

Syntax

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

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

Customization

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

#set heading(numbering: "1.")
#set math.equation(numbering: "(1)")

#show ref: it => {
  let eq = math.equation
  let el = it.element
  if el != none and el.func() == eq {
    // Override equation references.
    link(el.location(),numbering(
      el.numbering,
      ..counter(eq).at(el.location())
    ))
  } else {
    // Other references as usual.
    it
  }
}

= Beginnings <beginning>
In @beginning we prove @pythagoras.
$ a^2 + b^2 = c^2 $ <pythagoras>

Fields

target: Label

Implementations

impl RefElem

pub fn new(target: Label) -> Self

Create a new instance of the element.

pub fn with_supplement(self, supplement: Smart<Option<Supplement>>) -> Self

Builder-style setter for the supplement field.

pub fn with_form(self, form: RefForm) -> Self

Builder-style setter for the form field.

pub fn with_citation(self, citation: Option<Packed<CiteElem>>) -> Self

Builder-style setter for the citation field.

pub fn with_element(self, element: Option<Content>) -> Self

Builder-style setter for the element field.

pub fn push_supplement(&mut self, supplement: Smart<Option<Supplement>>)

Setter for the supplement field.

pub fn push_form(&mut self, form: RefForm)

Setter for the form field.

pub fn push_citation(&mut self, citation: Option<Packed<CiteElem>>)

Setter for the citation field.

pub fn push_element(&mut self, element: Option<Content>)

Setter for the element field.

pub fn supplement<'a>( &'a self, styles: StyleChain<'a>, ) -> &'a Smart<Option<Supplement>>

A supplement for the reference.

If the form is set to {"normal"}:

• For references to headings or figures, this is added before the referenced number.
• For citations, this can be used to add a page number.

If the form is set to {"page"}, then this is added before the page number of the label referenced.

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

#set heading(numbering: "1.")
#show ref.where(
  form: "normal"
): set ref(supplement: it => {
  if it.func() == heading {
    "Chapter"
  } else {
    "Thing"
  }
})

= Introduction <intro>
In @intro, we see how to turn
Sections into Chapters. And
in @intro[Part], it is done
manually.

pub fn form(&self, styles: StyleChain<'_>) -> RefForm

The kind of reference to produce.

#set page(numbering: "1")

Here <here> we are on
#ref(<here>, form: "page").

pub fn citation(&self) -> Option<&Option<Packed<CiteElem>>>

A synthesized citation.

pub fn element(&self) -> Option<&Option<Content>>

The referenced element.

pub fn supplement_in(styles: StyleChain<'_>) -> &Smart<Option<Supplement>>

Access the supplement field in the given style chain.

pub fn form_in(styles: StyleChain<'_>) -> RefForm

Access the form field in the given style chain.

pub fn set_supplement(supplement: Smart<Option<Supplement>>) -> Property

Create a style property for the supplement field.

pub fn set_form(form: RefForm) -> Property

Create a style property for the form field.

Trait Implementations

impl Capable for RefElem

fn vtable(capability: TypeId) -> Option<NonNull<()>>

Get the pointer to the vtable for the given capability / trait.

impl Clone for RefElem

fn clone(&self) -> RefElem

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Construct for RefElem

fn construct(engine: &mut Engine<'_>, args: &mut Args) -> SourceResult<Content>

Construct an element from the arguments.

impl Debug for RefElem

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Fields for RefElem

type Enum = Fields

An enum with the fields of the element.

fn has(&self, id: u8) -> bool

Whether the element has the given field set.

fn field(&self, id: u8) -> Result<Value, FieldAccessError>

Get the field with the given field ID.

fn field_with_styles( &self, id: u8, styles: StyleChain<'_>, ) -> Result<Value, FieldAccessError>

Get the field with the given ID in the presence of styles.

fn field_from_styles( id: u8, styles: StyleChain<'_>, ) -> Result<Value, FieldAccessError>

Get the field with the given ID from the styles.

fn materialize(&mut self, styles: StyleChain<'_>)

Resolve all fields with the styles and save them in-place.

fn fields(&self) -> Dict

Get the fields of the element.

impl Hash for RefElem

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoValue for RefElem

fn into_value(self) -> Value

Cast this type into a value.

impl NativeElement for RefElem

fn data() -> &'static NativeElementData

Get the element data for the native Rust element.

fn elem() -> Element

where Self: Sized,

Get the element for the native Rust element.

fn pack(self) -> Content

where Self: Sized,

Pack the element into type-erased content.

impl PartialEq for RefElem

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

const fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Repr for RefElem

fn repr(&self) -> EcoString

Return the debug representation of the value.

impl Set for RefElem

fn set(engine: &mut Engine<'_>, args: &mut Args) -> SourceResult<Styles>

Parse relevant arguments into style properties for this element.