michaelchirico/bslib

Tools for theming Shiny and R Markdown via Bootstrap 3, 4, or 5.

bslib

The bslib R package provides tools for customizing Bootstrap themes directly from R, making it much easier to customize the appearance of Shiny apps & R Markdown documents. bslib’s primary goals are:

• Make custom theming as easy as possible.
  • Custom themes may even be created interactively in real-time.
• Also provide easy access to pre-packaged Bootswatch themes.
• Make upgrading from Bootstrap 3 to 4 (and beyond) as seamless as possible.
  • Shiny and R Markdown default to Bootstrap 3 and will continue to do so to avoid breaking legacy code.
• Provide useful wrappers around modern Bootstrap (and CSS) components, such as cards, value boxes, layouts, and more.
• Serve as a general foundation for Shiny and R Markdown extension packages.
  • Extensions such as flexdashboard, pkgdown, and bookdown already fully support bslib’s custom theming capabilities.

Installation

Install the stable release of bslib on CRAN:

install.packages("bslib")

Usage with Shiny requires version 1.6 or higher:

install.packages("shiny")

Usage with R Markdown requires version 2.7 or higher:

install.packages("rmarkdown")

Basic usage

bslib is designed for use with any Shiny or R Markdown project that uses Bootstrap. In most cases, you can identify a project that uses Bootstrap when the relevant page constructor has a theme parameter. For example, most Shiny page layout functions (e.g., shiny::navbarPage()) and some popular R Markdown formats (e.g., rmarkdown::html_document) all have a theme parameter.

To use bslib in Shiny, provide a bs_theme() object to the theme parameter; and in R Markdown, provide bs_theme() parameters to theme. For example, here’s a way to upgrade Shiny (left) and R Markdown (right) from Bootstrap 3 to 5:

library(shiny)
ui <- navbarPage(
  theme = bs_theme(version = 5),
  ...
)
shinyApp(ui, function(...) {})

---
output:
  html_document:
    theme:
      version: 5
---

See the Get Started article to learn more about Bootstrap versions, pre-packaged Bootswatch themes, (real-time) custom theming, and more.

To get started more quickly, choose a relevant R Markdown template from inside RStudio by going to File -> New File -> R Markdown -> From Template:

Getting help

There are two main places to get help with bslib:

• The RStudio community is a friendly place to ask any questions (be sure to add a bslib tag when creating a topic).

• Stack Overflow is a great source of answers to common bslib questions. It is also a great place to get help, once you have created a reproducible example that illustrates your problem. Use the tags [r][bslib] if you ask a question. Add the tag [bslib] if you are using a Shiny runtime.

Code of Conduct

Please note that the bslib project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.