CRAN status Lifecycle: experimental R build status

bslib (formerly known as bootstraplib)

The {bslib} R package provides tools for creating custom Bootstrap themes, making it easier to style Shiny apps & R Markdown documents directly from R without writing unruly CSS and HTML. At the moment, {bslib} provides special builds of Bootstrap 4 & 3 that “just work” with Shiny & R Markdown.

Installation

To install the stable release from CRAN:

install.packages("bslib")

Getting Started

Create a theme

Use bs_theme() to create a {bslib} theme, where you can:

For example, to implement a material design inspired dark mode:

library(bslib)
my_theme <- bs_theme(
  bg = "#202123", fg = "#B8BCC2", primary = "#EA80FC", 
  base_font = font_google("Grandstander"),
  "font-size-base" = "1.1rem"
)

Shiny usage

Note: this usage requires Shiny v1.6 or higher install.packages("shiny").

To use my_theme inside of Shiny, pass it to the relevant theme parameter in page functions such as shiny::navbarPage(), shiny::fluidPage(), shiny::bootstrapPage(), etc.

library(shiny)
ui <- navbarPage(
  theme = my_theme,
  ...
)
shinyApp(ui, function(input, output) {})

For a preview of how my_theme impacts most of Shiny UI’s styling defaults, provide it to bs_theme_preview(). This preview app includes most “core” Shiny UI functionality as well as an interactive “real-time” theming widget for quickly testing out new colors and fonts. To help replicate those styling changes, the widgets also emits code to the R console. It can also be used with other Shiny apps via run_with_themer() (or bs_themer()).

bs_theme_preview(my_theme)

More generally, you can use a Bootstrap theme with any HTML page by using shiny::bootstrapLib() to provide the theme as an htmltools::htmlDependency() to an shiny::htmlTemplate() or any HTML htmltools::tags that you wish, for example:

library(shiny)
ui <- htmlTemplate(
  "my-template.html",
  theme = my_theme,
  ...
)
shinyApp(ui, function(input, output) {})
<!-- my-template.html -->
<!DOCTYPE html>
<html>
  <head>
    {{ headContent() }}
    {{ bootstrapLib(theme) }}
  </head>
  <body>
    ...
  </body>
</html>

R Markdown usage

Note: this usage currently requires the development version of R Markdown remotes::install_github("rstudio/rmarkdown")

To use a bs_theme() in R Markdown, pass the relevant theming parameter(s) to the theme parameter of html_document (or, really, anything that runs through html_document_base):

---
output:
  html_document:
    theme:
      bg: "#202123"
      fg: "#B8BCC2"
      primary: "#EA80FC"
      base_font: !expr bslib::font_google("Grandstander")
---

At the moment, {bslib} is a opt-in feature in R Markdown (i.e., whenever theme is a list or a bs_theme(), then {bslib} is used). This means that, to use the default bslib::bs_theme():

---
output:
  html_document:
    theme: !expr bslib::bs_theme()
---

Moreover, when opting into {bslib}, you may modify theme object globally inside knitr code chunks. This can be useful for things like adding additional CSS rules that leverage Bootstrap Sass variables, functions, mixins, etc:

```{r}
library(bslib)
bs_global_add_rules(
  ".my-class { 
     background-color: mix($body-bg, $body-color, 90%);
     border: 1px solid $primary;
     @include border_radius($border-radius);
   }
  "
)
```

Add to a theme

bs_theme() customizes Bootstrap CSS by changing Bootstrap Sass variable defaults, but sometimes you need to customize the theme in other ways by adding other Sass code. For example, if you’d like to add Sass/CSS rules for a custom, themable, component:

my_theme %>%
  bs_add_rules(
    ".my-component { color: $primary; }"
  )

Learn more

To learn more, see the theming article.