Customize Shiny app appearance using bslib's Bootstrap 5 theming system. From quick Bootswatch themes to advanced Sass customization and dynamic color mode switching.
\n\"shiny\" preset (recommended starting point):
\npage_sidebar(\n theme = bs_theme(), # \"shiny\" preset by default — polished, not plain Bootstrap\n ...\n)\nBootswatch theme (for a different visual style):
\npage_sidebar(\n theme = bs_theme(preset = \"zephyr\"), # or \"cosmo\", \"minty\", \"darkly\", etc.\n ...\n)\nCustom colors and fonts:
\npage_sidebar(\n theme = bs_theme(\n version = 5,\n bg = \"#FFFFFF\",\n fg = \"#333333\",\n primary = \"#2c3e50\",\n base_font = font_google(\"Lato\"),\n heading_font = font_google(\"Montserrat\")\n ),\n ...\n)\nAuto-brand from _brand.yml:\nIf a _brand.yml file exists in your app or project directory, bs_theme() automatically discovers and applies it. No code changes needed. Requires the brand.yml R package.
bs_theme(brand = FALSE) # Disable auto-discovery\nbs_theme(brand = TRUE) # Require _brand.yml (error if not found)\nbs_theme(brand = \"path/to/brand.yml\") # Explicit path\n\"shiny\" preset (default) or a Bootswatch theme close to your desired lookbg, fg, primary)font_google() or other font helpers... or bs_add_variables()bs_add_rules() if neededthematic::thematic_shiny() so plots match the themebs_themer() during development for interactive previewExample:
\ntheme <- bs_theme(preset = \"minty\") |>\n bs_theme_update(\n primary = \"#1a9a7f\",\n base_font = font_google(\"Lato\")\n ) |>\n bs_add_rules(\"\n .card { box-shadow: 0 2px 8px rgba(0,0,0,0.1); }\n \")\nCentral function for creating Bootstrap themes. Returns a sass::sass_bundle() object.
bs_theme(\n version = version_default(),\n preset = NULL, # \"shiny\" (default for BS5+), \"bootstrap\", or Bootswatch name\n ..., # Bootstrap Sass variable overrides\n brand = NULL, # brand.yml: NULL (auto), TRUE (require), FALSE (disable), or path\n bg = NULL, fg = NULL,\n primary = NULL, secondary = NULL,\n success = NULL, info = NULL, warning = NULL, danger = NULL,\n base_font = NULL, code_font = NULL, heading_font = NULL,\n font_scale = NULL, # Scalar multiplier for base font size (e.g., 1.5 = 150%)\n bootswatch = NULL # Alias for preset\n)\nUse bs_theme_update(theme, ...) to modify an existing theme. Use is_bs_theme(x) to test if an object is a theme.
The \"shiny\" preset (recommended): bs_theme() defaults to preset = \"shiny\" for Bootstrap 5+. This is a polished, purpose-built theme designed specifically for Shiny apps — it is not plain Bootstrap. It provides professional styling with well-chosen defaults for cards, sidebars, value boxes, and other bslib components. Start here and customize with colors and fonts before reaching for a Bootswatch theme.
Vanilla Bootstrap: Use preset = \"bootstrap\" to remove the \"shiny\" preset and get unmodified Bootstrap 5 styling.
Built-in presets: builtin_themes() lists bslib's own presets.
Bootswatch themes: bootswatch_themes() lists all available Bootswatch themes. Choose one that fits the app's purpose and audience — don't apply one by default.
Popular options: \"zephyr\" (light, modern), \"cosmo\" (clean), \"minty\" (fresh green), \"flatly\" (flat design), \"litera\" (crisp), \"darkly\" (dark), \"cyborg\" (dark), \"simplex\" (minimalist), \"sketchy\" (hand-drawn).
The most influential colors — changing these affects hundreds of CSS rules via variable cascading:
\n| Parameter | \nDescription | \n
|---|---|
bg | \nBackground color | \n
fg | \nForeground (text) color | \n
primary | \nPrimary brand color (links, nav active states, input focus) | \n
secondary | \nDefault for action buttons | \n
success | \nPositive/success states (typically green) | \n
info | \nInformational content (typically blue-green) | \n
warning | \nWarnings (typically yellow) | \n
danger | \nErrors/destructive actions (typically red) | \n
bs_theme(\n bg = \"#202123\", fg = \"#B8BCC2\",\n primary = \"#EA80FC\", secondary = \"#48DAC6\"\n)\nColor tips:
\nbg/fg: similar hue, large luminance difference (ensure contrast for readability)primary: contrasts with both bg and fg; used for hyperlinks, navigation, input focushtmltools::parseCssColors() understandsThree font arguments: base_font, heading_font, code_font. Use font_scale to uniformly scale all font sizes (e.g., 1.5 for 150%).
Each argument accepts a single font, a font_collection(), or a character vector of font names.
Downloads and caches Google Fonts locally (local = TRUE by default). Internet needed only on first download.
bs_theme(\n base_font = font_google(\"Roboto\"),\n heading_font = font_google(\"Montserrat\"),\n code_font = font_google(\"Fira Code\")\n)\nWith variable weights: font_google(\"Crimson Pro\", wght = \"200..900\")
With specific weights: font_google(\"Raleway\", wght = c(300, 400, 700))
Recommend fallbacks to avoid Flash of Invisible Text (FOIT) on slow connections:
\nbs_theme(\n base_font = font_collection(\n font_google(\"Lato\", local = FALSE),\n \"Helvetica Neue\", \"Arial\", \"sans-serif\"\n )\n)\nFont pairing resource: fontpair.co
\nCSS web font interface for custom font URLs:
\nfont_link(\"Crimson Pro\",\n href = \"https://fonts.googleapis.com/css2?family=Crimson+Pro:wght@200..900\")\nFor locally hosted font files with full @font-face control:
font_face(\n family = \"Crimson Pro\",\n style = \"normal\",\n weight = \"200 900\",\n src = \"url(fonts/crimson-pro.woff2) format('woff2')\"\n)\nCombine multiple fonts with fallback order:
\nfont_collection(font_google(\"Lato\"), \"Helvetica Neue\", \"Arial\", \"sans-serif\")\nFor customizations beyond bs_theme()'s named parameters. These work directly with Bootstrap's Sass layers.
Add or override Bootstrap Sass variable defaults:
\ntheme <- bs_add_variables(\n bs_theme(preset = \"sketchy\", primary = \"orange\"),\n \"body-bg\" = \"#EEEEEE\",\n \"font-family-base\" = \"monospace\",\n \"font-size-base\" = \"1.4rem\",\n \"btn-padding-y\" = \".16rem\"\n)\nThe .where parameter controls placement in the Sass compilation order:
.where | \nWhen to use | \n
|---|---|
\"defaults\" (default) | \nSet variable defaults with !default flag. Placed before Bootstrap's own defaults. | \n
\"declarations\" | \nReference other Bootstrap variables (e.g., $secondary). Placed after Bootstrap's defaults. | \n
\"rules\" | \nPlaced after all rules. Rarely needed. | \n
Referencing Bootstrap variables:
\n# This fails in bs_theme() because $secondary isn't defined yet:\n# bs_theme(\"progress-bar-bg\" = \"$secondary\")\n\n# Use bs_add_variables with .where = \"declarations\" instead:\nbs_theme() |>\n bs_add_variables(\"progress-bar-bg\" = \"$secondary\", .where = \"declarations\")\nAdd custom Sass/CSS rules that can reference Bootstrap variables and mixins:
\ntheme <- bs_theme(primary = \"#007bff\") |>\n bs_add_rules(\"\n .custom-card {\n background: mix($bg, $primary, 95%);\n border: 1px solid $primary;\n padding: $spacer;\n\n @include media-breakpoint-up(md) {\n padding: $spacer * 2;\n }\n }\n \")\nFrom external file: bs_add_rules(sass::sass_file(\"www/custom.scss\"))
Available Sass functions: lighten(), darken(), mix(), rgba(), color-contrast().\nAvailable Bootstrap mixins: @include media-breakpoint-up(), @include box-shadow(), @include border-radius().
Add custom Sass functions or mixins to the theme bundle:
\ntheme |>\n bs_add_functions(\"@function my-tint($color) { @return mix(white, $color, 20%); }\") |>\n bs_add_rules(\".highlight { background: my-tint($primary); }\")\nAppend sass::sass_bundle() objects to a theme (for packaging reusable theme extensions):
my_extension <- sass::sass_layer(\n defaults = list(\"my-var\" = \"red !default\"),\n rules = \".my-class { color: $my-var; }\"\n)\ntheme <- bs_theme() |> bs_bundle(my_extension)\nPass any Bootstrap 5 Sass variable through bs_theme(...) or bs_add_variables().
Finding variable names: https://rstudio.github.io/bslib/articles/bs5-variables/
\nCommon variables:
\nbs_theme(\n \"border-radius\" = \"0.5rem\",\n \"card-border-radius\" = \"1rem\",\n \"card-bg\" = \"lighten($bg, 5%)\",\n \"navbar-bg\" = \"$primary\",\n \"link-color\" = \"$primary\",\n \"font-size-base\" = \"1rem\",\n \"spacer\" = \"1rem\",\n \"btn-padding-y\" = \".5rem\",\n \"btn-padding-x\" = \"1rem\",\n \"input-border-color\" = \"#dee2e6\"\n)\nValues can be Sass expressions referencing variables, functions, and math.
\nSee sass-and-css-variables.md for details on:
\n--bs-* CSS custom propertiesdata-bs-themeSee dark-mode.md for details on:
\ndata-bs-theme attribute)input_dark_mode() and toggle_dark_mode() for user-controlled switchingsession$setCurrentTheme()bs_theme() only affects CSS. R plot output (rendered server-side as images) won't auto-match. Use the thematic package:
library(thematic)\nthematic_shiny(font = \"auto\") # Call before shinyApp()\nshinyApp(ui, server)\nfont = \"auto\" also matches fonts from bs_theme()bs_themer() for real-time previewSet global ggplot2 theme for further consistency:
\nlibrary(ggplot2)\ntheme_set(theme_minimal())\nThe bslib-page-dashboard CSS class adds a light gray background behind the main content area, giving dashboard-style apps a polished look where cards stand out against the background. This is a theming detail — it doesn't change layout behavior, only the visual treatment.
For page_sidebar() dashboards:
page_sidebar(\n class = \"bslib-page-dashboard\",\n title = \"My Dashboard\",\n sidebar = sidebar(...),\n ...\n)\nFor page_navbar() with dashboard-focused pages:\nApply the class to individual nav_panel() containers (not page_navbar() itself) so only dashboard-oriented pages get the gray background:
page_navbar(\n title = \"Analytics\",\n nav_panel(\"Dashboard\", class = \"bslib-page-dashboard\",\n layout_column_wrap(...)\n ),\n nav_panel(\"Report\",\n # No dashboard class — standard white background for prose/reports\n ...\n )\n)\nStandalone demo app for previewing a theme with many example UI components:
\nbslib::bs_theme_preview() # Default theme\nbslib::bs_theme_preview(bs_theme(preset = \"darkly\")) # Custom theme\nIncludes the theming UI by default (with_themer = TRUE).
Run an existing Shiny app with the theme editor overlay (instead of shiny::runApp()):
run_with_themer(shinyApp(ui, server))\nrun_with_themer(\"path/to/app\")\nAdd the theme editor to your own app's server function:
\nserver <- function(input, output, session) {\n bs_themer() # Add during development, remove for production\n # ...\n}\nAll three tools print the resulting bs_theme() code to the R console for easy copy-paste. Limitations: Bootstrap 5+ only, Shiny apps and runtime: shiny R Markdown only, doesn't affect 3rd-party widgets that don't use bs_dependency_defer().
Retrieve computed Sass variable values:
\nvars <- c(\"body-bg\", \"body-color\", \"primary\", \"border-radius\")\nbs_get_variables(bs_theme(), varnames = vars)\nbs_get_variables(bs_theme(preset = \"darkly\"), varnames = vars)\nCheck contrast (for accessibility):
\nbs_get_contrast(bs_theme(), c(\"primary\", \"dark\", \"light\"))\nAim for WCAG AA compliance: 4.5:1 for normal text, 3:1 for large text.
\nbs_theme() over custom CSS -- variables cascade to all related components automaticallybs_theme(version = 5) prevents breakage if defaults changefont_collection() to avoid FOIT on slow connectionsbs_get_contrast() and browser dev toolstheme.R:# theme.R\napp_theme <- function() {\n bs_theme(\n version = 5,\n primary = \"#2c3e50\",\n base_font = font_google(\"Lato\"),\n heading_font = font_google(\"Montserrat\", wght = c(400, 700))\n ) |>\n bs_add_rules(sass::sass_file(\"www/custom.scss\"))\n}\n