In rstudio/bootstraplib: Custom 'Bootstrap' 'Sass' Themes for 'shiny' and 'rmarkdown'

library(bslib)

knitr::opts_chunk$set(
  ## Screenshots are created during `devtools::document()` in CI
  ## or set to `TRUE` below to test or update locally
  # .update_screenshot = TRUE,
  "fig.width" = 5,
  "fig.height" = 2.5,
  "dpi" = 100
)

The appearance of a value_box() can be controlled via the theme argument in one of two ways: 1. a character value describing the theme, such as theme = "primary" or theme = "blue"; or 3. theme = value_box_theme() to create a custom theme.

We recommend using named themes for most value boxes (the first approach), because these themes will automatically match your Bootstrap theme.

Named themes

Bootstrap provides a list of theme colors, with semantic names like "primary", "secondary", "success", "danger", etc. You can set theme to one of these names to use the corresponding theme color as the background color of your value box.

value_box(
  title = "Customer lifetime value",
  value = "$5,000",
  showcase = bsicons::bs_icon("bank2"),
  theme = "primary"
)

Bootstrap's theme colors are drawn from a second color list that includes variations on several main colors, named literally. These colors include "blue", "purple", "pink", "red", "orange", "yellow", "green", "teal", and "cyan".

value_box(
  title = "Customer lifetime value",
  value = "$5,000",
  showcase = bsicons::bs_icon("bank2"),
  theme = "teal"
)

Background colors

If the theme or color name is provided without any prefix, the color will be used for the background of the value box. You can also explicitly prefix the theme or color name with bg- to indicate that it should apply to the value box background. When the theme sets the background color, either black or white is chosen automatically for the text color using Bootstrap's color contrast algorithm.

As before, you can reference semantic theme color names or literal color names.

value_box(
  title = "Customer lifetime value",
  value = "$5,000",
  showcase = bsicons::bs_icon("bank2"),
  theme = "bg-success"
)

value_box(
  title = "Customer lifetime value",
  value = "$5,000",
  showcase = bsicons::bs_icon("bank2"),
  theme = "bg-purple"
)

Foreground colors

To set only the foreground colors of the value box, you can prefix the theme or color name with text-. This changes the text color without affecting the background color.

value_box(
  title = "Customer lifetime value",
  value = "$5,000",
  showcase = bsicons::bs_icon("bank2"),
  theme = "text-success"
)

value_box(
  title = "Customer lifetime value",
  value = "$5,000",
  showcase = bsicons::bs_icon("bank2"),
  theme = "text-purple"
)

Occasionally you may want to adjust use both background and foreground themes on your value box. To achieve this, set theme to one of the theme names and use class for the complementary style. The example below uses theme = "purple" (which could also be "bg-purple") for a purple background, and class = "text-light" for light-colored text.

value_box(
  title = "Customer lifetime value",
  value = "$5,000",
  showcase = bsicons::bs_icon("bank2"),
  theme = "purple",
  class = "text-light"
)

Gradient backgrounds

For a vibrant and attention-grabbing effect, bslib provides an array of gradient background options. Provide theme with a theme name in the form bg-gradient-{from}-{to}, where {from} and {to} are named main colors, e.g. bg-gradient-indigo-blue.

value_box(
  title = "Customer lifetime value",
  value = "$5,000",
  showcase = bsicons::bs_icon("bank2"),
  theme = "bg-gradient-indigo-blue"
)

Custom colors

Finally, for complete customization, you can use value_box_theme() to create a custom theme. This function takes arguments bg and fg to set the background and foreground colors, respectively. Like with the bg- theme names, if only bg is provided, value_box_theme() will choose an appropriate light or dark color for the text color.

value_box(
  title = "Customer lifetime value",
  value = "$5,000",
  showcase = bsicons::bs_icon("bank2"),
  theme = value_box_theme(bg = "#e6f2fd", fg = "#0B538E"),
  class = "border"
)

Note that value_box_theme() optionally takes a theme name, which can be helpful if you want to use a named theme and modify the default bg or fg colors of that theme.

value_box_theme(name = "orange", bg = "#FFFFFF")
value_box_theme(name = "text-danger", fg = "#FFB6C1")

Also note that bg/fg must be CSS colors, not Bootstrap theme or color names. This means that theme = "purple" will use your Bootstrap theme's purple color, and bg = "purple" will use the CSS color for purple, i.e. "r htmltools::parseCssColors("purple")".

rstudio/bootstraplib documentation built on June 17, 2024, 9:42 a.m.