bootstraplib
The {bootstraplib} R package provides tools for creating custom
Bootstrap
themes,
making it easier to style Shiny apps and R Markdown documents directly
from R without writing unruly CSS and HTML. Currently, {bootstraplib}
provides Bootstrap 4, Bootstrap 3, as well as a custom "4+3"
compatibility version, which helps upgrade Shiny and R Markdown from
Bootstrap 3 to 4.
Installation
{bootstraplib} isn’t yet available from CRAN, but you can install
with:
remotes::install_github("rstudio/bootstraplib")Getting Started
Create a theme
Use bs_theme() to create a {bootstraplib} theme, where you can:
-
Choose a (major) Bootstrap version.
- To current
version_default()is 4+3, which means Bootstrap 4 plus an additional compatibility layer for Bootstrap 3 navs, navbars, and more. This compatibility allows most Shiny apps and R Markdown documents to seamlessly upgrade to Bootstrap 4.
- To current
-
Choose a Bootswatch theme (optional).
-
Customize the main colors and fonts (see below).
-
More generally, customize any of Bootstrap’s styling defaults via Sass variables.
For example, to implement a material design inspired dark mode:
library(bootstraplib)
my_theme <- bs_theme(
bg = "#202123", fg = "#B8BCC2", primary = "#EA80FC",
base_font = "Grandstander"
)Shiny usage
Note: this usage requires the development version of Shiny
remotes::install_github("rstudio/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(ui, server) {})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(ui, server) {})<!-- my-template.html -->
<!DOCTYPE html>
<html>
<head>
{{ headContent() }}
{{ bootstrapLib(theme) }}
</head>
<body>
...
</body>
</html>R Markdown usage
Note: this usage currently requires an experimental version of R Markdown
remotes::install_github("rstudio/rmarkdown#1706")
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: "Grandstander"
---For backwards-compatibility reasons, R Markdown only uses
{bootstraplib} when theme is a list of parameters, so if you want to
just use Bootstrap 4 without any custom theming, you must do:
---
output:
html_document:
theme:
version: 4+3
---Moreover, when theme depicts a bs_theme(), you may modify the
(global) theme in knitr code chunks to influence the final
Bootstrap CSS bundle included in the output document. This means you can
do things like dynamically modify theme default(s) (with
bs_global_theme_update() ) and/or add additional CSS rules that
leverage Bootstrap Sass variables, functions, mixins, etc:
```{r}
library(bootstraplib)
bs_global_theme_update("input-bg" = "purple")
bs_global_add_rules(
".my-class {
background-color: mix($body-bg, $body-color, 90%);
border: 1px solid $primary;
@include border_radius($border-radius);
}
"
)
```
Learn more
See the articles on theming recipes and foundations.
