bootstraplib

Tools for styling shiny and rmarkdown from R via Bootstrap (3 or 4) Sass.

Installation

bootstraplib isn’t yet available from CRAN, but you can install with:

remotes::install_github("rstudio/bootstraplib")
library(bootstraplib)

Introduction

The bootstraplib R package provides tools for compiling and working with Bootstrap Sass, making it possible to style shiny apps and rmarkdown documents directly from R (via sass) instead of writing raw CSS and HTML. Currently, bootstraplib supports Bootstrap 3 and 4, as well as a special "4+3" compatibility version (read more about this in choosing a version). Using bootstraplib in shiny and rmarkdown is still considered experimental at this point, but see the notes below to start using it today.

Shiny

To start using bootstraplib in your shiny apps today, install remotes::install_github("rstudio/shiny"), then do the following:

1. Call bs_theme_new() and optionally specify a Bootstrap version and bootswatch theme. The current default is Bootstrap 4 (with added added Bootstrap 3 compatibility) and no bootswatch theme:

bs_theme_new(version = "4+3", bootswatch = NULL)

2. Once a (global) theme is initialized, you may start adding theming customizations; for example overriding variable defaults, and more (see the theming foundations article).

bs_theme_add_variables(
  "body-bg" = "salmon",
  "body-color" = "white"
)

3. Add bootstrap() to your user interface (this step might not be required in a future version of shiny).

library(shiny)
fluidPage(
  bootstrap(),
  titlePanel("Hello world!")
)

R Markdown

To start using bootstraplib in your rmarkdown::html_documents, install remotes::install_github("rstudio/rmarkdown#1706"), then do the following:

1. Use bootstrap_version and theme to choose the Bootstrap version and a Bootswatch theme. These arguments are currently supported only in html_document and html_document_base.

---
output:
  html_document:
    bootstrap_version: 4+3
    theme: minty
---

2. Optionally add theme customizations inside any R code chunk (these customizations end up influencing the Bootstrap CSS included in the output document).

   library(bootstraplib)
   bs_theme_add_variables(primary = 'salmon')

Choosing a version

The bootstraplib package currently supports three different versions: "4+3", 4, and 3. In the future, when Bootstrap releases more major versions, bootstraplib may add more versions, and may also change the default version. However, the default version (currently "4+3") will always be designed to work well with core shiny UI functionality (e.g., actionButton(), navlistPanel(), etc). If your UI wants to assume a specific version of Bootstrap (i.e., it uses a package like bs4Dash or yonder to generate UI), then it’s a good idea to set an explicit version (this way, when a new version of Bootstrap is released, and the default version changes, your app won’t break).

Be aware that Bootstrap 4 and 3 expose a very different set of theme customization entry points, and as a result, theme customizations that you write for Bootstrap 4 may not necessarily work for Bootstrap 3 (and vice versa). At the moment, our priority is to enable and improve the Bootstrap 4 theming experience. If you’re not interested in upgrading to Bootstrap 4, and would rather theme your Bootstrap 3 project today, you may want to consider using fresh in the near term.

Interactive theming

bootstraplib also comes with tools for interactive theming of shiny apps (and rmarkdown documents with runtime: shiny). Either point run_with_themer() to an existing application or use bs_theme_preview() to use a pre-packaged application designed for theming. Note that as you interactively theme your application, code is printed to the R console that you can copy/paste to adopt those changes in your theming code.

bs_theme_new(bootswatch = "sketchy")
bs_theme_preview()

Learn more

See the articles on theming recipes and foundations.

Similar work

The fresh package offers an alternative (& currently more user friendly) approach to theming via Bootstrap 3 Sass variables. At the moment, bootstraplib is more focused on laying an extensible foundation for theming with Bootstrap 3 (or 4) that other R packages can build upon.