How-to: Use bslib with Rhino

Introduction

The bslib R package is a UI toolkit based on Bootstrap. Shiny uses it under the hood for its default appearance, but it’s also possible to use bslib directly to gain access to:

1. Additional components (e.g. value boxes, accordions, tooltips).
2. Customization and theming.
3. A refined interface (e.g. bslib::page_sidebar instead of shiny::sidebarLayout).
4. The latest Bootstrap (v5).

Rhino comes with built-in support for writing custom Sass code in app/styles/main.scss. This guide explains how to combine bslib and custom Sass code, allowing you to:

1. Share variables (e.g. colors and fonts) between bslib and custom Sass.
2. Use Bootstrap variables, functions and mixins in your custom Sass.
3. Further customize Bootstrap, e.g. override its mixins.

If you don’t want to write any custom Sass, you can use bslib as you would normally without any additional setup.

Steps

1. Add bslib to project dependencies: rhino::pkg_install("bslib").
2. Use sass: custom configuration option in rhino.yml.
3. Bundle Rhino Sass with bslib theme, e.g.:

theme <- bslib$bs_theme(primary = "purple") |>
  bslib$bs_add_rules(sass$sass_file("app/styles/main.scss"))

You can create the theme object in app/main.R or in a dedicated file, e.g. app/view/theme.R. You need to define your UI using one of bslib::page_* layout functions, and pass the theme object as argument, e.g.:

#' @export
ui <- function(id) {
  ns <- NS(id)
  bslib$page_fillable(
    theme = theme,
    shiny$h1("Hello!")
  )
}

You don’t need to run rhino::build_sass(). Shiny will build it automatically when needed.

With this setup you can use the main.scss file as you would normally, but with full access to Bootstrap and variables defined in bs_theme(), e.g.:

h1 {
  color: tint-color($primary, 20%);
}

Advanced use cases

For advanced use cases, consider creating a complete Sass layer:

theme <- bslib$bs_bundle(
  bslib$bs_theme(),
  sass$sass_layer(
    functions = sass$sass_file("app/styles/functions.scss"),
    defaults = sass$sass_file("app/styles/defaults.scss"),
    mixins = sass$sass_file("app/styles/mixins.scss"),
    rules = sass$sass_file("app/styles/rules.scss")
  )
)