Figures & Layout

Quarto includes a number of features aimed at making it easier to work with figures and subfigures, as well as for laying out panels that contain multiple figures, tables, or other content.

Figure Basics

In Pandoc markdown, a figure is created whenever a captioned image appears by-itself in a paragraph. For example:

![Elephant](elephant.png)

This results in the following treatment for various output types:

HTML PDF Word
A line drawing of an elephant. A line drawing of an elephant. A line drawing of an elephant.

Note that for LaTeX / PDF output figures are automatically numbered (you can arrange for figures to be numbered in other formats using Cross References).

Linked Figures

When rendering with Quarto, you can enclose a figure within a link and it will still be treated within output as a captioned figure. For example:

[![Elephant](elephant.png)](https://en.wikipedia.org/wiki/Elephant)

Figure Alignment

Figures and their captions are center aligned by default. Add the fig-align attribute to the image to use a different alignment. For example:

![Elephant](elephant.png){fig-align="left"}

Alt Text

You can add alternative text to a figure by adding the fig-alt attribute to the image. For example, the following Markdown…

![](elephant.png){fig-alt="A drawing of an elephant."}

… will create the following HTML with the corresponding alt tag:

<img src="elephant.png" alt="A drawing of an elephant.">

Note that the figure caption, title, and alt text can all be different. For example, the following code…

![Elephant](elephant.png "Title: An elephant"){fig-alt="A drawing of an elephant."}

…produces this HTML:

<img src="elephant.png" title="Title: An elephant" alt="A drawing of an elephant.">

LaTeX Environments

There are a number of LaTeX packages that provide custom figure environments. For example, the mdframed package includes an mdframed environment used to enclose figures in a special border style. By default, Quarto uses the standard figure environment, but you can use the fig-env attribute to specify a custom one. For example:

---
title: "Sidenotes"
format:
  pdf:
    header-includes: |
      \usepackage{sidenotes}
---

![Elephant](elephant.png){fig-env="marginfigure"}

Figure Divs

You can treat any markdown content you want as a figure by enclosing it in Pandoc div block with an identifier prefaced with #fig-. For example, here we create a figure that includes an embedded iframe:

::: {#fig-elephant}

<iframe width="560" height="315" src="https://www.youtube.com/embed/SNggmeilXDQ"></iframe>

Elephant
:::

Note that the last paragraph in the div block is used as the figure caption.

Subfigures

If you have several figures that appear as a group, you can create a figure div to enclose them. For example:

::: {#fig-elephants layout-ncol=2}

![Surus](surus.png){#fig-surus}

![Hanno](hanno.png){#fig-hanno}

Famous Elephants
:::

Again, the last paragraph provides the main caption, and the individual figures carry the sub-captions. Here is what this looks like when rendered as HTML:

An artistic rendition of Surus, Hannibal's last war elephant, is on the left. Underneath this picture is the caption '(a) Surus.' On the right is a line drawing of Hanno, a famous elephant. Underneath this picture is the caption '(b) Hanno.' The words 'Figure 1: Famous elephants' are centered beneath both pictures.

Note that we also used a layout-ncol attribute to specify a two-column layout. The next section delves more into customizing figure layouts.

Figure Panels

Above we demonstrate laying out two side-by-side figures with subcaptions and a main caption. You may or may not want the caption / sub-caption treatment, and you might also want to use multiple rows of figures. All of these variations are possible.

To layout two figures with their own standalone captions (and no main caption), just eliminate the #fig identifiers and main caption at the bottom:

::: {layout-ncol=2}
![Surus](surus.png)

![Hanno](hanno.png)
:::

An artistic rendition of Surus, Hannibal's last war elephant, is on the left. Underneath this picture is the caption 'Surus.' On the right is a line drawing of Hanno, a famous elephant. Underneath this picture is the caption 'Hanno.'

You can also eliminate the captions entirely:

::: {layout-ncol=2}
![](surus.png)

![](hanno.png)
:::

Multiple Rows

If you have more than 2 images, you might want to lay them out across multiple rows. You can do this using the layout-nrow attribute. For example:

::: {layout-nrow=2}
![Surus](surus.png)

![Hanno](hanno.png)

![Abdul Abbas](abdul-abbas.png)

![Lin Wang](lin-wang.png)
:::

A 2x2 grid of pictures of elephants. There are labels underneath each of the pictures. Clockwise from the upper left, the labels say: Surus, Hanno, Lin Wang, and Abdul Abbas.

More complex figure arrangements (e.g. rows with varying column layouts) are possible. See the Complex Layouts section below for more details.

Table Panels

You can also use a div with layout attributes to display tables side-by-side. For example:

::: {layout-ncol=2}
| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | C    |
| E    | F    | G    |
| A    | G    | G    |

: First Table

| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | C    |
| E    | F    | G    |
| A    | G    | G    |

: Second Table
:::

Two tables side by side. The table on the left is titled 'First Table'. This table has 4 rows and 3 columns. The first row contains the column title, which are bolded and are separated from the rest of the table by an upper and lower border. The column titles are, from left to right, 'Col1', 'Col2', and 'Col3'. The values in the first row underneath the lower border of the column rows are 'A', 'B', 'C'. The values of the next row under that are 'E', 'F', 'G'. The final row contains 'A', 'G', 'G'. There is a border underneath the last row. The second table is identical to the first except that its title is 'Second Table.'

As with figures, you can also present tables using numbered subcaptions by adding a main caption and #tbl- identifiers:

::: {#tbl-panel layout-ncol=2}
| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | C    |
| E    | F    | G    |
| A    | G    | G    |

: First Table {#tbl-first}

| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | C    |
| E    | F    | G    |
| A    | G    | G    |

: Second Table {#tbl-second}

Main Caption
:::

Two tables side by side. The table on the left is titled '(a) First Table'. This table has 4 rows and 3 columns. The first row contains the column title, which are bolded and are separated from the rest of the table by an upper and lower border. The column titles are, from left to right, 'Col1', 'Col2', and 'Col3'. The values in the first row underneath the lower border of the column rows are 'A', 'B', 'C'. The values of the next row under that are 'E', 'F', 'G'. The final row contains 'A', 'G', 'G'. There is a border underneath the last row. The second table is identical to the first except that its title is ' (b)Second Table.' Centered underneath both tables is the caption 'Table 1: Main Caption.'

See the article on Cross References for additional details on table captions, subcaptions, and numbering.

Custom Layouts

The examples above used the layout-ncol or layout-nrow attributes to create straightforward layouts where all columns are of equal sizes. The layout attribute enables the creation of much more complex layouts.

For example, this defines a layout with two equally sized figures in the first row, then another image that spans the entire second row:

::: {layout="[[1,1], [1]]"}
![Surus](surus.png)

![Hanno](hanno.png)

![Lin Wang](lin-wang.png)
:::

Three elephant pictures arranged such that two pictures are side-by-side in the first row, and the third picture is underneath both of these. The picture on the left in the first row is captioned 'Surus' and the picture on the right is captioned 'Hanno'. The picture underneath these two is captioned 'Lin Wang' and is as as wide and tall as the other two put together.

The layout attribute is a 2-dimensional array where the first dimension defines rows and the second columns. In this case "layout="[[1,1], [1]]" translates to: create two rows, the first of which has two columns of equal size and the second of which has a single column.

Note that the numbers in a row are arbitrary and don’t need to add up to a particular total. You can therefore use whatever scheme is most natural. For example, here we define columns that occupy varying percentage widths of the row:

::: {layout="[[70,30], [100]]"}
![Surus](surus.png)

![Hanno](hanno.png)

![Lin Wang](lin-wang.png)
:::

You can also use negative values to create space between elements. For example:

::: {layout="[[40,-20,40], [100]]"}
![Surus](surus.png)

![Hanno](hanno.png)

![Lin Wang](lin-wang.png)
:::

Three elephant pictures arranged such that two pictures are side-by-side in the first row, and the third picture is underneath both of these. The picture on the left in the first row is captioned 'Surus' and the picture on the right is captioned 'Hanno'. The two pictures are separated by some whitespace. The picture underneath these two is captioned 'Lin Wang' and is wider and taller than the other two put together.

Vertical Alignment

If you have a layout with a row of images of differing heights, you can control their vertical alignment using the layout-valign attribute. A simple example:

::: {layout="[25,-2,10]" layout-valign="bottom"}
![Surus](surus.png)

![Lin Wang](lin-wang.png)
:::

Note that vertical alignment isn’t limited to images, you can also vertically align any other elements that are included in a panel.

Computations

Figures

Note that figure layout attributes also work for figures produced by executable code blocks. Here are examples for both Jupyter and Knitr:

```{python}
#| layout-ncol: 2

import matplotlib.pyplot as plt
plt.plot([1,23,2,4])
plt.show()

plt.plot([8,65,23,90])
plt.show()
```

Two line plots rendered by Jupyter side-by-side.

```{r}
#| layout-ncol: 2

plot(cars)
plot(pressure)
```

Two scatter plots arranged side-by-side.

Tables

You can also use layout attributes for tables produced by Knitr or Jupyter. For example, this Rmd code chunk creates side-by-side tables:

```{r}
#| layout-ncol: 2

library(knitr)
kable(head(cars), caption = "Cars")
kable(head(pressure), caption = "Pressure")
```

Two tables arranged side by side. Both tables have two columns and 8 rows. The left-hand table is titled 'Cars'. The column names of this table are 'speed' and 'dist'. From top to bottom, the row values are: 4, 2; 4, 10; 7, 4; 7, 22; 8, 16; 9, 10. The table on the right is titled 'Pressure'. The column names are 'temperature' and 'pressure'. From top to bottom, the row values are: 0, 0.0002; 20, 0.0012; 40, 0.0060; 60, 0.0300; 80, 0.0900; 100, 0.2700.

Custom Layout

The layout works the same way for figures or tables produced by knitr or Jupyter. For example, here’s an Rmd code chunk that produces 3 plots and defines a custom layout for them:

```{r}
#| layout: [[45,-10, 45], [100]]

plot(cars)
plot(pressure)
plot(mtcars)
```

Two plots arranged side-by-side with a large plot underneath it. The top two plots are scatter plots visualizing the `cars` and `pressure` datasets. These two plots are separated by some additional white space. The plot on the bottom visualizes the `mtcars` dataset and is wider and taller than the other two plots combined. This plot is an 11 by 11 grid plotting each of the 11 variables in the `mtcars` dataset against each other as a scatterplot. Instead of scatter plots in the diagonal starting in the upper left and going to the lower right are text labels for each of the variable names. These are: 'mpg', 'cyl', 'disp', 'hp', 'drat', 'wt', 'qsec', 'vs', 'am', 'gear', and 'carb'.

Block Layout

While the examples above illustrate laying out figures and tables, it’s important to note that layout attributes can be used to layout any sort of block content. For example, here we layout 2 lists side-by-side:

::: {layout-ncol=2}
### List One

- Item A
- Item B
- Item C

### List Two

- Item X
- Item Y
- Item Z
:::

Note that headings are automatically combined with the block that follows them, so this markdown has a total of 2 columns to lay out. Here’s an example of a paragraph next to a bullet list (without headings):

::: {layout-ncol=2}
- Item X
- Item Y
- Item Z

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur gravida eu erat et fring. Morbi congue augue vel eros ullamcorper, eget convallis tortor sagittis. Fusce sodales viverra mauris a fringilla. Donec feugiat, justo eu blandit placerat, enim dui volutpat turpis, eu dictum lectus urna eu urna. Mauris sed massa ornare, interdum ipsum a, semper massa. 
:::