Skip to main content
v2026.11,986 entries · CC-BY 4.0

bslib: Bootstrap Theming and Dashboard Layouts for Shiny in R

bslib is an R package for Shiny and R Markdown: install it, build a sidebar-and-card dashboard, theme it with bs_theme(), and fix common layout problems.

Written and maintained by CASRAI Editorial Board

Published · Last updated

On this page

bslib is an R package that gives Shiny apps and R Markdown documents a modern Bootstrap-based user interface toolkit: page layouts with sidebars, cards, value boxes, column grids, navigation bars and a theming system that controls colours, fonts and Bootstrap variables from R code. Researchers use it to turn an analysis into a shareable dashboard without writing HTML or CSS by hand. Install it with install.packages("bslib"); the package is on CRAN and released under the MIT license.

What bslib is used for in research

The bslib project site describes the package as “a modern UI toolkit for Shiny and R Markdown based on Bootstrap”. In a research setting that means two jobs. The first is layout: arranging the controls, summary numbers and figures of an interactive analysis so that a collaborator, reviewer or funder can explore a dataset without opening R. The second is theming: matching an app or report to a lab, project or institutional look, or switching between light and dark appearances, using a few arguments rather than custom stylesheets.

bslib sits underneath much of the R web-publishing stack. The CRAN page for the package lists rmarkdown, shiny, pkgdown, flexdashboard, bs4Dash, teal and esquisse among the packages that import it, so even if you never call it directly, parts of your output may already depend on it. If you are building an app for the first time, start with the Shiny interface guide, which covers the app structure that bslib’s page functions plug into, and return here when you want a cleaner layout or a custom theme.

One fact explains why the package exists. The bslib documentation states that Shiny and R Markdown currently default to Bootstrap 3 for backward compatibility. bslib is the opt-in route to newer Bootstrap versions: its CRAN description lists support for Bootstrap 3, 4 and 5 and for Bootswatch themes. Nothing changes in an existing app until you pass a bslib theme or use a bslib page function.

How to install or access it

bslib is distributed through CRAN. The CRAN package page listed version 0.12.0, published 2026-08-04 (checked 2026-11-14), with Carson Sievert as maintainer and Joe Cheng and Garrick Aden-Buie among the authors; Posit Software, PBC is named as copyright holder and funder. Install and load it in the usual way:

install.packages("bslib")library(shiny)library(bslib)

The package’s own demonstration needs nothing else. Running bslib::bs_theme_preview() launches a demo Shiny app with the theming widget already overlaid, which is the quickest way to see what a theme change does before you touch your own code. The examples in the dashboard article additionally use ggplot2, palmerpenguins (for the penguins dataset), dplyr, bsicons (icons), scales (number formatting) and lorem (placeholder text); install only the ones you need for the features you copy. The same article recommends thematic so that plots drawn by plotOutput() pick up the colours of the CSS theme.

Step-by-step task: build a research dashboard with bslib

The steps below follow the documented dashboard pattern from the bslib site, using the palmerpenguins data as a stand-in for any measurements table. Replace the dataset and the plot code with your own analysis.

  1. Load the packages. Run library(shiny) and library(bslib).
  2. Start with page_sidebar(). The documentation says to quickly create a dashboard by providing a title, a sidebar and the main area contents. The minimal form is page_sidebar(title = "My dashboard", sidebar = "Sidebar", "Main content area").
  3. Put the controls in sidebar(). Wrapping the sidebar contents in sidebar() lets you add a title and adjust styling and position. In the documented example the sidebar holds a varSelectInput() for choosing a numeric variable and a numericInput() for the number of histogram bins.
  4. Put each output in a card(). A card with a header is written card(card_header("Histogram"), plotOutput("p")). Adding full_screen = TRUE to a card lets the reader expand it to fill the screen.
  5. Add headline numbers with value_box(). The documentation calls it a special kind of card designed for highlighting a value along with a title and a showcase placeholder. A documented call is value_box(title = "Average bill length", value = ..., showcase = bsicons::bs_icon("align-bottom")).
  6. Arrange cards with layout_columns(). Column widths are given out of 12: layout_columns(col_widths = c(4, 8, 12), row_heights = c(1, 2), ...) places a four-wide and an eight-wide card on the first row and a full-width card on the second. Without col_widths, space is divided evenly among the elements in a row, and negative widths leave empty space.
  7. Split a card with layout_sidebar(). This component-level function gives one card its own local controls, for example layout_sidebar(sidebar = sidebar(title = "Local controls", position = "right", "..."), plotOutput("bill_length")), and it can be placed inside card().
  8. Move to several pages with page_navbar(). Change page_sidebar() to page_navbar() and supply each page with nav_panel("Title", content). nav_spacer() and nav_item() add spacing and custom items to the bar. A sidebar given to page_navbar() appears on every page.
  9. Apply a theme. Pass a bs_theme() object to the theme argument of the page function, for example page_sidebar(theme = bs_theme(bootswatch = "minty")). For a custom palette, bs_theme(bg = "#101010", fg = "#FFF", primary = "#E69F00", base_font = font_google("Inter"), code_font = font_google("JetBrains Mono")) is the documented dark example. The documentation notes that bg, fg and primary have the broadest effect.
  10. Tune the theme interactively. Call bs_themer() inside the server function to get a live theming widget on your running app, then copy the values you like back into bs_theme().

Worked example: a penguin-measurements dashboard

This is the documented sidebar-and-card pattern, shortened. The penguins table stands in for a research dataset with several numeric measurements.

library(shiny)library(bslib)data(penguins, package = "palmerpenguins")ui = page_sidebar(  title = "Penguins dashboard",  sidebar = sidebar(    title = "Histogram controls",    varSelectInput("var", "Select variable", dplyr::select_if(penguins, is.numeric)),    numericInput("bins", "Number of bins", 30)  ),  card(card_header("Histogram"), plotOutput("p")))

Read it from the outside in. page_sidebar() supplies the page frame and title; sidebar() holds the two inputs; the single card() holds the plot output that your server code fills. To grow the dashboard, add value_box() summaries above the card and wrap them with the card inside layout_columns(), as in the steps above. Because the structure is declarative, a collaborator can read the user-interface code and see at a glance which controls exist and which outputs they drive. If you later want to host the finished app, the shinyapps.io guide covers one deployment route, and for interactive charts inside cards the plotly in R guide is a natural companion.

Output and how to read it

The output of a bslib app is a rendered page, not a file. In a browser you should see a title bar, a sidebar on the left containing your inputs, and the main area filled with cards. Three behaviours are worth recognising so that they are not mistaken for faults.

  • Filling layout. Cards in page_sidebar() and page_navbar() stretch to use the available height, because fillable defaults to TRUE. A plot that resizes with the window is this behaviour working.
  • Collapsed sidebar on small screens. On mobile devices the sidebar is collapsed by default and the reader opens it with its toggle.
  • Full-screen cards. A card created with full_screen = TRUE shows an expand control so a reader can inspect one figure at full size.

When you share an app, remember that the reader sees the theme exactly as you set it; colour choices that are legible on your monitor should also be checked in the light and dark variants if you offer both. The documentation shows a manual dark-mode switch: define light = bs_theme() and dark = bs_theme(bg = "black", fg = "white", primary = "purple"), add a checkboxInput("dark_mode", "Dark mode"), and in the server call session$setCurrentTheme() with whichever theme the checkbox selects, wrapped in observe().

Custom styling beyond bs_theme()

Beyond the main colours, the theming article describes three further levers. Extra named arguments to bs_theme() set Bootstrap Sass variables, for example bs_theme("progress-bar-bg" = "mix(white, orange, 20%)"). bs_add_variables() adds variables to an existing theme and, with .where = "declarations", places the definition after Bootstrap so it can refer to Bootstrap’s own variables. bs_add_rules() appends CSS or Sass rules, either as a string such as "body { background-color: $body-bg; }" or from a file with sass::sass_file("custom.scss"). For R Markdown, the same article sets theme options under output: html_document: theme: in the YAML header, for example bootswatch: minty.

Troubleshooting

Cards are squashed or the page will not scroll as expected

Filling layout is on by default. Set fillable = FALSE on page_sidebar() or page_navbar() to turn it off, or, in page_navbar(), pass a vector of page names such as fillable = c("Bill Length", "Bill Depth") to keep it on for only those pages. On individual cards, set height for a card that should neither grow nor shrink, and min_height or max_height for one that should not shrink or grow past a limit, for example card(min_height = 200, plotOutput("bill_length")).

The layout fills on desktop but not on a phone

Filling layout is not enabled on mobile devices by default, so fillable is effectively FALSE there. Setting fillable_mobile = TRUE enables it. The sidebar is also collapsed on mobile; use the open argument of sidebar() to change that.

The sidebar shows on pages where it does not belong

A sidebar supplied to page_navbar() appears on every page. If only some pages need controls, use layout_sidebar() inside the relevant pages’ cards instead.

The look changes after a package update

Shiny and R Markdown default to Bootstrap 3 unless a bslib theme says otherwise. The dashboards article recommends pinning the Bootstrap version in the theme before deploying to production, for example page_sidebar(theme = bs_theme(version = 5), ...), so that a later change of defaults does not alter a published app.

Plot colours clash with the theme

If plots drawn by plotOutput() do not match the theme, the documentation recommends the thematic package to match plot styles to the CSS theme.

bs_themer() does nothing

It must be called in a running Shiny context, that is, inside the server function. In R Markdown it needs runtime: shiny and theme: bslib: true in the YAML.

bslib itself is open source (MIT license per CRAN). The options below are the other routes to a Shiny or R Markdown interface that the sources describe; they are complements and defaults rather than rivals, and you can combine them.

Option What it is Relationship to bslib (from the sources)
Shiny’s default page functions such as fluidPage() The standard way to lay out a Shiny app Default to Bootstrap 3; a bslib theme can be passed through the theme argument (the dynamic-theming example uses fluidPage(theme = light))
R Markdown html_document themes Static or Shiny-runtime documents Themed through output: html_document: theme:, for example bootswatch: minty
flexdashboard An R Markdown dashboard format Listed on CRAN among the packages that import bslib
bs4Dash, teal, esquisse Other Shiny-based packages Each is listed on CRAN as importing bslib

The data table below maps each bslib function to the job it does, so you can pick the right one for a given layout or theming task.

Frequently asked questions

What is bslib?

bslib is an R package that provides a modern user-interface toolkit for Shiny and R Markdown, built on Bootstrap. It supplies page layouts, cards, value boxes, navigation and a theming system.

Which Bootstrap versions does bslib support?

According to its CRAN description, bslib supports Bootstrap 3, 4 and 5 and Bootswatch themes. Shiny and R Markdown still default to Bootstrap 3 for backward compatibility.

How do I install bslib?

Run install.packages("bslib") in R. The package is available from CRAN.

Can I use bslib in R Markdown as well as Shiny?

Yes. The project site describes bslib as a toolkit for both. In Shiny you pass bs_theme() to a page function’s theme argument; in R Markdown you set theme options in the html_document YAML.

How can I preview themes without editing my app?

Run bslib::bs_theme_preview() to launch a demo app with the live theming widget. In your own app, call bs_themer() inside the server function.

What licence does bslib use?

CRAN lists the MIT license. For how open-source software is defined and cited in research, see the open-source software entry in the CASRAI dictionary.

Sources

Data: bslib functions mapped to the job they do

Compiled from the bslib dashboards and theming articles and the CRAN page: each row names a bslib function, its level in the toolkit, the job it does and the main arguments the documentation shows for it.

Period covered: 2026.

bslib functions mapped to the job they do
FunctionLevelJob (as documented)Main arguments shown in the docs
page_sidebar()PageDashboard page with a title, a sidebar and main contenttitle, sidebar, fillable, fillable_mobile, theme
page_navbar()PageMulti-page layout with a navigation bar; a sidebar given here appears on every pagetitle, sidebar, fillable
nav_panel()NavigationSupplies the title and content of one page in a navbartitle, content
sidebar()ComponentSidebar with its own title, styling and position; collapsed on mobile by defaulttitle, open, position
layout_sidebar()ComponentSidebar layout for one component, usable inside a cardsidebar, position
card()ComponentContainer for an output; can expand to full screenfull_screen, height, min_height, max_height
card_header()ComponentHeader inside a cardtext
value_box()ComponentCard that highlights one value with a title and a showcase placeholdertitle, value, showcase
layout_columns()LayoutMulti-column grid with widths out of 12; even split without col_widthscol_widths, row_heights
bs_theme()ThemingCreates a theme: Bootswatch, main colours, fonts and Sass variablesbootswatch, bg, fg, primary, base_font, code_font
bs_add_variables()ThemingAdds Sass variables to a theme; .where = 'declarations' places them after Bootstrapvariables, .where
bs_add_rules()ThemingAppends CSS or Sass rules or files to a themerules
bs_themer()ThemingLive theming widget; called inside the server functionnone
bs_theme_preview()ThemingLaunches a demo Shiny app with the theming widget overlaidnone

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about bslib: Bootstrap Theming and Dashboard Layouts for Shiny in R

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →