In bslib: 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
)

Use the showcase argument to add a plot or icon to your value_box(). There are three layouts available: "left center", "top right", and "bottom". Set showcase to the name of the layout you'd like, or use the showcase_left_center(), showcase_top_right(), or showcase_bottom() helper functions to customize the showcase area's size.

If you're using a plot as your showcase, you may also want to set fullscreen = TRUE so that your users can expand the value box into a full screen card. See the value box article for more details.

Left-center showcase

The "left center" showcase layout is the default, and is perfect for an icon or a small plot. This layout works best for short value boxes.

value_box(
  title = "Energy consumption",
  value = "345 kwh/month",
  showcase = bsicons::bs_icon("ev-station-fill")
)

Top-right showcase

The "top right" showcase layout places the icon or plot in the upper right corner of the value box. This layout works best for medium-height to square value boxes.

value_box(
  title = "Energy consumption",
  value = "345 kwh/month",
  showcase = bsicons::bs_icon("ev-station-fill"),
  showcase_layout = "top right"
)

Bottom showcase

Finally, the "bottom" showcase layout is perfect for full-bleed plots. This layout places the plot below the title and value, with the plot taking up the full width of the bottom half.

Try this layout with sparkline-style plots. These can be a little tricky to set up, so be sure to check out the Expandable sparklines section of the value boxes article on the bslib website. In this example, we've created a sparkline plot using base R graphics, which isn't generally recommended. \if{latex}{View the bslib documentation online to see the source of \verb{sparkline_plot()}.}

#| fig.width: 10
#| fig.show: hide

set.seed(4242)

random_sparkline_plot <- function() {
  timeseries <- cumsum(runif(100, -2, 2))
  x_axis <- seq_along(timeseries)
  x_lim <- c(1, length(timeseries))
  y_lim <- range(timeseries) + c(-2, 0)

  par(mar = c(0, 0, 0, 0))

  # Set up the plot area
  plot(
    timeseries, type = "n",
    axes = FALSE, frame.plot = FALSE,
    ylim = y_lim, xlim = x_lim,
    ylab = "",    xlab = "",
    yaxs = "i",   xaxs = "i",
  )

  # Add the sparkline line
  lines(timeseries, type = "l", pch = NA, col = "#0B538E", lwd = 3)

  # Create polygon coordinates for shading
  polygon_x <- c(1, x_axis, length(timeseries))
  polygon_y <- c(min(y_lim), timeseries, min(y_lim))

  # Add shading under the line
  polygon(polygon_x, polygon_y, col = "#e6f2fd", border = NA)
}

sparkline_plot <- function() {
  as_fill_item(
    htmltools::plotTag(
      random_sparkline_plot(),
      width = 500,
      height = 125,
      suppressSize = "xy",
      alt = paste(
        "A sparkline plot with a randomly-generated timeseries.",
        "The timeseries starts high and ends low, with lots of variation."
      )
    )
  )
}

x <- htmltools::withTags(
  .noWS = c("after-begin", "before-end"),
  details(
    summary("Code for a sparkline plot with base R"),
    pre(code(paste0(
      paste(knitr::knit_code$get("showcase-plot"), collapse = "\n"),
      "\n\n",
      trimws(paste(knitr::knit_code$get("sparkline_plot"), collapse = "\n"))
    )))
  )
)
x <- gsub("\n", "<br>", x)
cat(sprintf("\\if{html}{\\out{%s}}", x))

value_box(
  title = "Energy consumption",
  value = "345 kwh/month",
  showcase = sparkline_plot(),
  showcase_layout = "bottom"
)

bslib documentation built on Sept. 11, 2024, 7:49 p.m.