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
, andbookdown
already fully supportbslib
’s custom theming capabilities.
- Extensions such as
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(...) {})
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.