Dashboards
Overview
A dashboard arranges a document’s outputs (plots, tables, numbers, text) into
a grid of cards that fills the browser window. Add format: dashboard to the
front matter:
---
title: "Sales"
format: dashboard
---Headings lay the page out as rows and columns. Code cells and .card divs
become cards. Value boxes, sidebars and toolbars add summary numbers and
controls. The result is a single HTML page built on
Bootstrap and the
bslib card and sidebar components.
Dashboards in Quarto 2 follow Quarto 1’s dashboard format closely, so existing dashboards should port with few or no changes. Differences from Quarto 1 lists where they differ.
Layout
Rows and columns
Each level-2 heading (##) starts a row, and each level-3 heading (###)
inside it starts a column:
---
title: "Layout"
format: dashboard
---
## Row {height=70%}
```{r}
plot(cars)
```
## Row {height=30%}
### Column {width=40%}
```{r}
summary(cars)
```
### Column {width=60%}
```{r}
hist(cars$speed)
```Set orientation: columns to swap the roles: level-2 headings become columns
and level-3 headings become rows inside them.
format:
dashboard:
orientation: columnsThe orientation always follows nesting depth: under orientation: rows, a
## section is a row and a ### section inside it is a column, wherever the
headings appear. The heading text itself is not displayed; it only names the
section.
Sizing: height, width, fill and flow
Give a row a height or a column a width as an attribute on its heading.
Percentages share the space between siblings; other CSS units (300px,
20em) fix the size. Sections without a size share what is left.
By default a dashboard fills the window: rows stretch to use the full height
and cards grow with them. A card or section that should keep its natural
height instead flows. Add .flow to the heading (or .fill to force
filling):
## Row {.flow}Text-only cards flow automatically, so a row of explanatory text doesn’t stretch to half the page.
Scrolling
With scrolling: true the page grows with its content and scrolls, instead
of fitting the window:
format:
dashboard:
scrolling: truePages
Level-1 headings (#) split the dashboard into pages, listed as tabs in the
navigation bar:
# Overview
## Row
...
# Details {orientation="columns" scrolling="true"}
## Column
...A page can set its own orientation and scrolling. The page in the URL hash
(dashboard.html#details) opens first, so you can link to a page directly.
Cards
Cells and .card divs
Every code cell with output becomes a card. A cell’s title option gives the
card a title:
```{r}
#| title: "Stopping distance"
plot(cars)
```Any markdown can go in a card through a .card div:
::: {.card title="About this dashboard"}
The data come from the 1920s `cars` dataset.
:::Card options, on the cell or the div:
| Option | Effect |
|---|---|
title
|
The card’s header text. Inline markdown (code, emphasis) works. |
padding
|
Padding around the card body, e.g. padding: 0.
|
height
|
A fixed height, as for rows. |
expandable
|
false removes the button that opens the card full screen.
|
.fill / .flow
|
Whether the card stretches or keeps its natural height. |
Cards are expandable by default. Set expandable: false under
format: dashboard to turn that off for every card.
Tabsets
Add .tabset to a row or column heading to show its cards as tabs inside one
card. Each card’s title becomes its tab label:
## Row {.tabset}
```{r}
#| title: "Speed"
hist(cars$speed)
```
```{r}
#| title: "Distance"
hist(cars$dist)
```Value boxes
A value box shows a single number with a title and an optional icon. Write it
as a .valuebox div whose first paragraph (or heading) is the title and
second is the value:
::: {.valuebox icon="pencil" color="primary"}
Articles per day
45
:::Or produce it from a cell with content: valuebox, printing a list (R) or a
dict (Python) with value and, optionally, icon and color:
```{r}
#| content: valuebox
#| title: "Spam"
list(icon = "trash", color = "danger", value = 12)
```The output is read, not evaluated. If it doesn’t have the expected shape,
Quarto warns (Q-27-1) and shows the printed
text as the value.
iconis a Bootstrap Icons name.coloris a Bootstrap theme color (primary,success,danger, …) or any CSS color.bg-colorandfg-colorset the background and text colors separately.showcase-position(orshowcase) moves the icon:left-center(the default),top-rightorbottom.
Dashboards in websites
A page with format: dashboard can be part of a website. It keeps the site’s
navigation bar, with the dashboard’s own bar (title and page tabs) under it,
and the site footer. It uses the site’s format: html theme unless the page
sets a theme of its own.
Previewing
q2 preview shows a live preview of a dashboard that updates as you edit,
with working page tabs, card tabs, sidebars and full-screen cards.
Differences from Quarto 1
Quarto 2 fixes several Quarto 1 dashboard bugs rather than reproducing them:
- Orientation follows nesting depth. Quarto 1 flipped it on every change of heading level, so a deeper heading before shallower ones could turn rows into columns.
.filland.flowon a row or column heading size the grid, as the Quarto 1 documentation describes.- A toolbar’s
heightis honored. - Headings inside sidebars and toolbars are demoted, as they are in cards.
content: sidebarandcontent: toolbarcells work.- A value box’s title can be a paragraph or a heading, and it always shows. Quarto 1 nested paragraphs, which hid the documented form’s title.
showcase-positionis honored, withshowcaseas an alias.header-forandfooter-foraccept the card’s or cell’s own id. Quarto 1 failed with an error.- A card toolbar or sidebar that finds no card is a warning with a location, not a fatal error or a silent drop.
- A card’s
heightis no longer copied onto its body. - Empty rows and columns are dropped consistently. Quarto 1 kept the last empty one.
- A single-page dashboard with a dark theme gets the toggle in its navigation bar. Quarto 1 only added it with pages.
- Share links leave out the title when the document has none, instead of
title=undefined. - In a website, the site’s html theme is used only when the dashboard page sets no theme. Quarto 1 replaced even the page’s own theme.
Not yet supported
- Shiny (
server: shiny) and Observable JS dashboards. - Interactive DataTables / itables tables. Static markdown tables work.
- Arranging several outputs in one card with
layout-ncol. title,paddingandcontentoptions on Jupyter (Python, Julia) cells: they are not passed on yet, so such cells become untitled cards andcontent: valueboxhas no effect. R (knitr) cells,.cardand.valueboxdivs work.- The
githubnav-button alias. Give the repository URL as a link instead. - The dark-mode toggle in the live preview.