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.
- Load the packages. Run
library(shiny)andlibrary(bslib). - Start with
page_sidebar(). The documentation says to quickly create a dashboard by providing atitle, asidebarand the main area contents. The minimal form ispage_sidebar(title = "My dashboard", sidebar = "Sidebar", "Main content area"). - Put the controls in
sidebar(). Wrapping the sidebar contents insidebar()lets you add a title and adjust styling and position. In the documented example the sidebar holds avarSelectInput()for choosing a numeric variable and anumericInput()for the number of histogram bins. - Put each output in a
card(). A card with a header is writtencard(card_header("Histogram"), plotOutput("p")). Addingfull_screen = TRUEto a card lets the reader expand it to fill the screen. - 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 isvalue_box(title = "Average bill length", value = ..., showcase = bsicons::bs_icon("align-bottom")). - 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. Withoutcol_widths, space is divided evenly among the elements in a row, and negative widths leave empty space. - Split a card with
layout_sidebar(). This component-level function gives one card its own local controls, for examplelayout_sidebar(sidebar = sidebar(title = "Local controls", position = "right", "..."), plotOutput("bill_length")), and it can be placed insidecard(). - Move to several pages with
page_navbar(). Changepage_sidebar()topage_navbar()and supply each page withnav_panel("Title", content).nav_spacer()andnav_item()add spacing and custom items to the bar. A sidebar given topage_navbar()appears on every page. - Apply a theme. Pass a
bs_theme()object to thethemeargument of the page function, for examplepage_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 thatbg,fgandprimaryhave the broadest effect. - Tune the theme interactively. Call
bs_themer()inside theserverfunction to get a live theming widget on your running app, then copy the values you like back intobs_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()andpage_navbar()stretch to use the available height, becausefillabledefaults toTRUE. 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 = TRUEshows 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.
Free alternatives and related options
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
- bslib project site, rstudio.github.io/bslib, read 2026-11-14.
- CRAN package page, cran.r-project.org/web/packages/bslib, read 2026-11-14.
- bslib article “Dashboards”, rstudio.github.io/bslib/articles/dashboards, read 2026-11-14.
- bslib article “Theming”, rstudio.github.io/bslib/articles/theming, read 2026-11-14.
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.
| Function | Level | Job (as documented) | Main arguments shown in the docs |
|---|---|---|---|
| page_sidebar() | Page | Dashboard page with a title, a sidebar and main content | title, sidebar, fillable, fillable_mobile, theme |
| page_navbar() | Page | Multi-page layout with a navigation bar; a sidebar given here appears on every page | title, sidebar, fillable |
| nav_panel() | Navigation | Supplies the title and content of one page in a navbar | title, content |
| sidebar() | Component | Sidebar with its own title, styling and position; collapsed on mobile by default | title, open, position |
| layout_sidebar() | Component | Sidebar layout for one component, usable inside a card | sidebar, position |
| card() | Component | Container for an output; can expand to full screen | full_screen, height, min_height, max_height |
| card_header() | Component | Header inside a card | text |
| value_box() | Component | Card that highlights one value with a title and a showcase placeholder | title, value, showcase |
| layout_columns() | Layout | Multi-column grid with widths out of 12; even split without col_widths | col_widths, row_heights |
| bs_theme() | Theming | Creates a theme: Bootswatch, main colours, fonts and Sass variables | bootswatch, bg, fg, primary, base_font, code_font |
| bs_add_variables() | Theming | Adds Sass variables to a theme; .where = 'declarations' places them after Bootstrap | variables, .where |
| bs_add_rules() | Theming | Appends CSS or Sass rules or files to a theme | rules |
| bs_themer() | Theming | Live theming widget; called inside the server function | none |
| bs_theme_preview() | Theming | Launches a demo Shiny app with the theming widget overlaid | none |
Sources
- bslib article: Dashboards (accessed 2026-11-14)
- bslib article: Theming (accessed 2026-11-14)
- bslib on CRAN (accessed 2026-11-14)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







