Lightbox Figures
Overview
Quarto uses the GLightbox javascript library to add lightbox styling and behavior to images in your HTML documents. Lightbox images allow a reader to click to see a larger version of the image (including any caption).
For example, the following images have lightbox treatment:
To enable lightbox treatment for all images in a document add lightbox: true in the YAML header:
---
title: Simple Lightbox Example
lightbox: true
---
Enabling Lightbox
You can enable lightbox either for all images within a document, or for only selected images within a document. To enable lightbox for all images within a document, use the following yaml:
---
lightbox: true
---When lightbox is set to automatically select images, it will match any image used as a figure or which appears as a block (by itself within a paragraph). By default, images that appear inline with other content will not receive lightbox treatment.
Applying Lightbox to Specific Images
You can select specific images to receive the lightbox treatment by applying the lightbox class on the images you’d like to receive the treatment. In this case, there is no need to include lightbox in the front matter, the use of the lightbox class will automatically enable lightbox. For example:
---
title: Simple Lightbox Example
---
{.lightbox}
will result in the first image receiving a lightbox treatment, while the second image will not.
Disabling Lightbox Treatment
You can disable lightbox for the whole document using the following yaml:
---
lightbox: false
---When lightbox is explicitly disabled, no images will receive the lightbox treatment, even if the image is marked with a lightbox class (as described above).
Disabling Lightbox for Specific Images
If automatic lightboxing of images is enabled, you can select specific images to not receive the treatment by marking them with a no-lightbox class. For example:
---
title: Simple Lightbox Example
lightbox: auto
---
{.no-lightbox}In this example, the first image will receive the lightbox treatment, while the second image will not.
Galleries
In addition to simply providing a lightbox treatment for individual images, you can also group images into a ‘gallery’. When the user activates the lightbox, they will be able to page through the images in the gallery without returning to the main document. To create galleries of images, apply a group attribute (with a name) to the images that you’d like to gather into a gallery. Images with the same group name will be placed together in a gallery when given a lightbox treatment.
For example, the following three images will be treated as a gallery:
{group="my-gallery"}
{group="my-gallery"}
{group="my-gallery"}Options
Quarto supports a number of options to customize the ligthbox behavior for a document. Options include:
| Option | Description |
|---|---|
match |
Set this to auto if you’d like any image to be given lightbox treatment. If you omit this, only images with the class lightbox will be given the lightbox treatment. |
effect |
The effect that should be used when opening and closing the lightbox. One of fade, zoom, none. Defaults to zoom. |
desc-position |
The position of the title and description when displaying a lightbox. One of top, bottom, left, right. Defaults to bottom. |
loop |
Whether galleries should ‘loop’ to first image in the gallery if the user continues past the last image of the gallery. Boolean that defaults to true. |
css-class |
A class name to apply to the lightbox to allow css targeting. This will replace the lightbox class with your custom class name. |
A complete example:
---
title: Complete Lightbox Example
lightbox:
match: auto
effect: fade
desc-position: right
loop: false
css-class: "my-css-class"
---Per Image Attributes
The following options may be specified as attributes on individual images to control the lightbox behavior:
| Option | Description |
|---|---|
desc-position |
The position of the title and description when displaying a lightbox. One of top, bottom, left, right. Defaults to bottom |
Using Lightbox with Computational Cells
The Quarto lightbox treatment will use figure information for computational outputs. For example, the following plot will receive a lightbox treatment and will include a properly prefixed caption when the user zooms into the plot.
---
lightbox: auto
---
```{r}
#| label: fig-basic
#| fig-cap: Simple demo R plot
plot(1:10, rnorm(10))
```If your computational cell produces multiple subfigures, each of the subfigures will receive the lightbox treatment and when zoom, the user may page back and forth through the subfigures. For example, the following will produce a ‘gallery’ lightbox view which includes both of the subfigures, allowing the viewer to easily navigate between sub figures:
```{r}
#| label: fig-plots
#| fig-cap: |
#| The below demonstrates placing more than one image in a gallery. Note
#| the usage of the `layout-ncol` which arranges the images on the page
#| side by date. Adding the `group` attribute to the markdown images places
#| the images in a gallery grouped together based upon the group name
#| provided.
#| fig-subcap:
#| - "This is a caption for the first sub figure"
#| - "This is a caption for the second sub figure"
#| layout-ncol: 2
plot(ToothGrowth)
plot(PlantGrowth)
```Advanced Customization In Computations
Options for lightbox can be passed using the code cell option lightbox like the following:
```{r}
#| fig-cap: Simple demo R plot
#| lightbox:
#| group: r-graph
#| description: This is 1 to 10 plot
plot(1:10, rnorm(10))
```It is possible to create several plots, and group them in a lightbox gallery. Use list in YAML for options when you have several plots, on per plot.
```{r}
#| fig-cap:
#| - Caption for first plot
#| - Caption for second plot
#| lightbox:
#| group: cars
#| description:
#| - This is the decription for first graph
#| - This is the decription for second graph
plot(mtcars)
plot(cars)
```