Theming flexdashboard

Bootstrap and bslib

The flex_dashboard output format builds upon the Bootstrap CSS framework. Bootstrap is a library of reusable chunks of HTML, CSS, and JavaScript code that you can call on to modify your flexdashboard without writing that code yourself. Originally created by and for Twitter, it is a free and open source project; you can view the repository on GitHub.

The flex_dashboard output format includes a theme parameter for customizing the overall appearance of the dashboard. This parameter has special integration with the {bslib} package, which makes it easy to customize Bootstrap CSS styles directly from R.

bslib supports multiple versions of Bootstrap so that both new and legacy projects can leverage custom themes. If you are starting on a fresh project, we recommend choosing the latest supported version (currently, version: 4), but legacy projects may want to set version: 3:

---
output:
  flexdashboard::flex_dashboard:
    theme: 
      version: 4
---

---
output:
  flexdashboard::flex_dashboard:
    theme: 
      version: 4
      bootswatch: minty
---

---
output:
  flexdashboard::flex_dashboard:
    theme:
      version: 4
      bg: "#101010"
      fg: "#FDF7F7" 
      primary: "#ED79F9"
      navbar-bg: "#3ADAC6"
      base_font: 
        google: Prompt
      heading_font:
        google: Sen
      code_font:
        google: 
          # arguments to sass::font_google() 
          family: JetBrains Mono
          local: false
---

Real-time theming

{bslib}’s real-time theming widget allows you to interactively customize theme: by adding:

• runtime: shiny to the document’s yaml matter and calling bslib::bs_themer() in any code chunk, or

• runtime: shinyrmd to the document’s yaml matter and calling bslib::bs_themer() in a code chunk with context='server':

  ```{r setup, include = FALSE, context = "server"}
  bslib::bs_themer()
  ```

```{r setup, include = FALSE}
thematic::thematic_rmd(font = "auto")
```

Add CSS styles

Although custom theming is great for customizing Bootstrap and Flexdashboard CSS, you still may want to add more styling rules to customize the appearance of your dashboard. This file can contain plain CSS rules, like:

.my-purple {
  background-color: #da70d6;
}

For this, you can provide relevant file(s) to flex_dashboard’s css argument:

---
output:
  flexdashboard::flex_dashboard:
    css: my-custom-rules.css
---

Then use your CSS rules in the body of your dashboard, for example:

This is a <span class="my-purple">purple</span> word.

You may achieve the same result writing with Pandoc’s spans:

This is a [purple]{.my-purple} word.

You can also add CSS divs using Pandoc’s fenced Div blocks:

::: {.my-purple}
All of these words are purple.
:::

When knit, these blocks are translated into HTML like so:

<div class="my-purple">
<p>All of these words are purple.</p>
</div>

Here is the knitted output that includes these custom rules:

You can read more about Pandoc’s custom blocks in the R Markdown Cookbook.

Add Sass rules

Sass is a language designed for writing better CSS. Thankfully, the css parameters also understands .scss (i.e., Sass) file(s):

---
output:
  flexdashboard::flex_dashboard:
    css: my-sass-rules.scss
    theme: 
      version: 4
---

Sass files can contain plain CSS rules, as well as rules that use Bootstrap Sass variables. These variables are denoted by $ followed by a variable name, like $cyan:

.bs4-bright {
  background-color: $cyan;
  color: $orange;
}

Then in your text you may use raw HTML or Pandoc syntax (as shown above):

This is a [*bright*]{.bs4-bright} word.

::: {.bs4-bright}
All of these words are *bright*.
:::

Here is the knitted output that includes these custom rules:

You can find a full list of variables in vignette("bs4-variables", package = "bslib").

When compiled, those Sass rules have access to Bootstrap Sass variables, functions, and mixins. This allows you to write custom CSS styles in a “themeable” way and/or simply leverage useful Sass functions like color-contrast().

For example, we can use the Sass @extend rule in our .scss file to bundle together multiple Bootstrap variables and tell Sass that one selector should inherit the styles of another:

.error {
  background-color: $cyan;
  color: $white;

  &--serious {
    @extend .error;
    color: $warning;
    font-size: $display4-size;
  }
}

Then you can use those rules in the body of your dashboard:

::: {.error}
Uh oh...
:::

::: {.error--serious}
Time for a break.
:::

Here is the knitted output that includes these custom rules:

You may also reuse any fonts specified in your YAML with Sass variables.

So we could set up the following rule:

.pkg-name {
  background-color: $cyan;
  color: $white;
  font-family: $font-family-monospace;
  padding: .5rem;
}

Then use it in the body:

I like the [flexdashboard]{.pkg-name} package.

Here is the knitted output:

Resources

This vignette provides a brief overview of bslib’s integration with flexdashboard, but there’s a lot more to theming with bslib (i.e. Bootstrap Sass), sass (i.e., Sass), and thematic. To learn more, see:

• The bslib package docs: https://rstudio.github.io/bslib/
• The sass package docs (for writing Sass code in R): https://rstudio.github.io/sass/
• The thematic package docs (for theming plot output): https://rstudio.github.io/thematic/
• Sass language docs: https://sass-lang.com/documentation
• Bootstrap docs: https://getbootstrap.com/docs/4.0/