6  Quarto dashboards

In this session you should learn:

6.1 What is a dashboard?

A dashboard is a user interface that allows interaction with the content displayed. This goes beyond making a plot zoomable and have a tooltip, but it usually let’s the user customise views and change parameters to get different insights. Static dashboards provide a fixed view of data without frequent updates, while dynamic dashboards are updated frequently and allow more interaction.

From a visualisation perspective, dashboards allow for further interactions with the data than what the creator of a static plot could have determined to show. It is very common to have such dashboard-like displays of spatial data, think for example of Google Earth Engine custom applications or ArcGIS dashboards and story-maps.

6.1.1 When should I use Shiny?

R has several tools for dashboard creation, with the most famous being Shiny. Then you might be wondering why this lesson is not about Shiny apps but rather about Quarto dashboards. Two reasons:

  1. Quarto dashboards are fairly new, so even though they might not have the popularity of Shiny, they are getting used more and more.

  2. Quarto dashboards are much easier to create and learn than using Shiny.

This by no means is to be interpret as a “don’t use Shiny”. Actually, the contrary. The more customisation you want to give to your dashboard and tools, the more you will be needing what Shiny apps offers. You can include Shiny inside your Quarto dashboards as a matter of fact.

Criteria Quarto dashboards Quarto + Shiny
Aim Layout & organisation, limited interactivity Reactivity & interactivity1
Hosting Runs without a server Needs a server (e.g. Shinyapps.io)2
Performance Fast (pre-rendered) Slower (dynamic computation)
Updates Needs re-rendering Real time data updates possible
Audience Passive viewers Active users
Note

If you decide to use Shiny in your Quarto dashboard project and have problems with deploying with the server, write all the problems you encountered down. The Quarto + Shiny dashboard should still be able to built locally!

6.2 Dashboard basics

Your main guide to build a Quarto dashboard will be (surprise, surprise) the Quarto dashboard documentation. See the further reading section for more resources.

Navigation bar provides navigation between pages
Pages useful to divide data for more complex stories
Cards fundamental unit of quarto dashboards, containers of all data elements; cards correspond to code chunks that return an output
Rows/columns define where each card is placed in the dashboard
Tabsets groups of rows and columns to further divide content
Sidebars collapsible vertical panels for inputs; used for filters, tick boxes, etc.
Toolbars horizontal panels for inputs; used for filters, tick boxes, etc.

Figure 6.1: Dashboard components. Source: Çetinkaya-Rundel (2024)

6.3 Packages for interactivity

Most of the packages that allow interactivity in R are based on JavaScript. This interaction is enabled in R due to the htmlwidgets tools. You will find some of the packages based on this tool under its documentation.

You can also link this widgets with packages such as {crosstalk}. Not every widget is “crosstalk-enabled” but maybe more and more will be available in the future.

Crosstalk schema from {cubble} documentation

Crosstalk schema from {cubble} documentation

Here you have a non-exhaustive overview of some of the packages that you might find most useful.

6.4 Dashboard example

Dashboard deployed on GitHub pages | Quarto raw file

6.5 Publish your dashboard!

The easiest way (at least for me) to publish any HTML content you create with Quarto is via GitHub pages. A free account let’s you create a website from a public repository in a very easy way.

6.5.1 Requirements

  1. Get a Github account

  2. Install git - get some guidance here.

  3. Configure git on your computer - see the steps here.

  4. Set up HTTPS or SSH protocols - see here - sections 9 to 11

6.5.2 Step by step guide

Step 1: Create a new GitHub repository

  1. Go to your GitHub account > Repositories > New

  2. Give it a name and a description and click “Create repository”

Step 1: Prepare Your Quarto Project

  1. Open RStudio and create a new Quarto project:
    • Go to File > New Project > Version Control > Git.
    • Go back to your GitHub repository and copy the “https://…” displayed under Quick setup
  2. Add content to your dashboard:
    • Create an empty index.qmd file (or create additional .qmd files).
    • Include your visualisations, tables, text, etc.
    • When you have one single html file to show, then it is useful to call it index since this will be automatically be recognised as the landing page of your site.
    • If you have more complex websites (created e.g. with a Quarto website project), then the .qmd files are mostly organised inside a _quarto.yaml file. See more information on Quarto websites here.

Step 3: Render Your Quarto Dashboard

  1. Render the project to generate the .html file with Render

Step 4: Push Your Project to GitHub

  1. Commit and push the project to GitHub:

    git add .
git commit -m "Initial commit"
git branch -M main
git push origin main

Step 5: Configure GitHub Pages

  1. Go to your repository on GitHub.
  2. Navigate to Settings > Pages.
  3. Under Source, select:
    • Branch: main (or your default branch).
    • Folder: / (root) if your rendered files are in the root directory, or docs/ if you’ve configured Quarto to save the site in a docs folder.
  4. Save the settings. GitHub Pages will generate a public URL for your site.
    • This might take some time, be patient! Once the green tick shows next to the commit message, then it is ready.

Step 6: Access Your Published Dashboard

  • Visit the URL provided by GitHub Pages (usually https://<username>.github.io/<repository-name>).

6.6 Further reading:

  1. Key concepts for Shiny reactivity and interactivity

    Aspect Reactivity Interactivity
    Definition Internal mechanism that updates outputs based on input changes. The user’s ability to interact with the app through inputs.
    Focus Logic and relationships between inputs, outputs, and expressions. The experience of manipulating and exploring the app.
    Example A plot updates automatically when an input changes. A user uses sliders, buttons, or checkboxes to customize the plot.
    Dependency Defined by reactive inputs and outputs. Enabled by UI elements (e.g., sliders, dropdowns).
    ↩︎

  2. Free for smaller projects, otherwise has paid options. See an overview of deployment options here↩︎