Figures, Tables & Cross-references in Quarto

Learn how Quarto numbers and captions figures and tables, and how to cross-reference them automatically with @fig- and @tbl- labels so numbering never goes stale.

In a real report you refer to your outputs — “as Figure 1 shows” or “see Table 2”. Doing that numbering by hand is fragile: insert one figure and every later reference is wrong. Quarto numbers and links everything automatically through cross-references.

Captioning and labelling a figure

Give a plotting chunk two options — a label that starts with fig-, and a fig-cap caption:

```{r}
#| label: fig-scores
#| fig-cap: "Distribution of exam scores"
hist(scores)
```

Quarto renders the plot with a numbered caption (“Figure 1: Distribution of exam scores”). The fig- prefix is what tells Quarto this is a figure.

Referencing it in text

Anywhere in your prose, write @fig-scores. Quarto replaces it with the correct number and a clickable link:

The scores are roughly symmetric (@fig-scores).

renders as “The scores are roughly symmetric (Figure 1).” Add a figure earlier in the document and every number renumbers itself — the reference never goes stale.

Tables work the same way

Use a tbl- label and tbl-cap. This works for a Markdown table or a table produced by R with knitr::kable():

```{r}
#| label: tbl-summary
#| tbl-cap: "Summary statistics by group"
knitr::kable(summary_table)
```

Then reference it with @tbl-summary. The same pattern extends to equations (eq-), sections (sec-) and code listings — one consistent syntax.

The rule to remember

Two halves that must match:

1. Define with a prefixed label: #| label: fig-something.
2. Reference with an @ in front: @fig-something.

Get the prefix right (fig-, tbl-, eq-, sec-) and Quarto handles all the counting and linking. For worked examples, see cross-references in Quarto.

---

Next: Parameters & reports → — generate many reports from one template.