bslib gives Shiny a Bootstrap 5 interface without hand-written CSS

A UI toolkit underneath Shiny, not a replacement for it

The bslib R package provides a modern UI toolkit for Shiny and R Markdown based on Bootstrap. The framing matters, because bslib is often mistaken for a Shiny replacement. It is not. It is a component and theming layer that sits underneath Shiny and R Markdown, and the fact that it works in both is the point. The package facilitates two broad things. The first is the creation of customizable Shiny dashboards, where the underlying UI components such as cards, value boxes and sidebars are also designed to work in other contexts, in R Markdown for example. The second is custom theming of Shiny apps and R Markdown documents, and here the distinguishing capability is that apps can be themed interactively in real time, which means you change a setting and see the result rather than editing Sass and rebuilding. The repository topics list `shiny`, `rmarkdown`, `bootstrap`, `sass` and `htmltools`, which is the dependency surface of that layering.

Why Bootstrap 3 is still the default

The README states the compatibility position directly: Shiny and R Markdown currently default to Bootstrap 3 and may continue to do so to maintain backwards compatibility. This is the single most important fact for anyone evaluating the package, because it means adopting bslib is not a default and the default is old. The reasoning is straightforward and also a limitation. Bootstrap 3 is what a decade of existing Shiny applications were built against, with its grid, its component classes and its JavaScript behaviour, and changing the default would silently break layouts in applications the maintainers of Shiny did not write. So the path is opt-in, and the cost of opting in is that the visual result changes. Bootstrap 5 is a different layout system with different spacing and different component markup, so an app that upgrades its theme inherits layout differences that no amount of theming will hide. The package also supports modern Bootswatch themes, which is where most of the visual variety comes from, since Bootswatch is the theme family that supplies Bootstrap variants for Shiny.

Installing from CRAN and running the theme preview

Installation is the standard CRAN install.

``` r install.packages("bslib") ```

The fastest way to see what the package can do is to run a demo at the console, which launches an app containing both bslib and shiny UI components as well as a theming widget, `bslib::bs_themer()`, overlaid on the app.

That widget is the real-time theming feature in its smallest form. It lets you change the Bootswatch theme and the Bootstrap settings and watch the app's appearance change as you do, which is how you find a combination that works rather than guessing at values and restarting. The documentation links to a real-time theming article for the fuller picture. The current release is bslib 0.12.0, published on 2026-08-04, after 0.11.0 in May 2026 and 0.10.0 in January 2026, and the last push to the repository was on 2026-10-20, so the package is being worked on between releases rather than only at release time.

The components are usable outside Shiny

The part of the README that is easy to skim past is the note that the underlying UI components are also designed to work in other contexts. Cards, value boxes and sidebars are not locked inside a Shiny runtime, which means the same component vocabulary can be used in an R Markdown document, and a package author can rely on them without pulling in the whole Shiny dependency. That is the difference between a theming helper and a UI toolkit, and it is what makes bslib usable in static output and in other htmltools-based contexts. The `htmltools` topic tag in the repository confirms that relationship, since htmltools is the R package for customisable HTML components and bslib's components are built to plug into it. The practical consequence for an author is that the choice of components does not force a choice of runtime, and a document or a dashboard can share the same look without sharing a server.

The package is more than the README shows

The repository layout tells you how much sits behind the short README. There is the standard R package skeleton with `DESCRIPTION`, `NAMESPACE`, `R/`, `man/`, `tests/`, `vignettes/` and `inst/`, plus a `srcts/` directory holding TypeScript sources and a `build/` step that compiles them, which is how the JavaScript half of the components is produced. There is a `pkgdown/` directory for the documentation site, a `revdep/` directory for reverse dependency checks, a `tools/` directory, and a `README.Rmd` that generates the README. The `package.json` at the root shows the front-end toolchain: esbuild for bundling, TypeScript and tsc for type checking, eslint with the unicorn and prettier plugins for linting, lit for the web components, and a yarn workflow where `build` runs the checks before the bslib build. The engines field asks for Node 14 or newer and yarn 1.22 or newer. The package is published on CRAN and mirrored in the r-universe, which is the more common way R users get it today, and the licence is recorded as a custom one with the terms in the LICENSE and LICENSE.note files.

Where bslib is the wrong choice

There are two clear cases for not using it. The first is an existing application whose layout is built on Bootstrap 3 assumptions, where switching to a Bootstrap 5 theme changes the grid and the component markup and the work of fixing it is real. The package's own default exists precisely because that breakage is widespread enough to be worth avoiding, so a project with an existing user base and no appetite for visual regression testing should stay where it is. The second is a document or app that does not want Bootstrap at all. bslib is a Bootstrap toolkit, so if the design direction is something else, it offers nothing. There is also a scope limit worth stating: the theming widget and the component set are the product, and bslib is not a layout or design system, so the amount of visual identity it can give you is bounded by what Bootstrap and Bootswatch expose. The README points at getting started articles for Shiny dashboards, for any Bootstrap project and for theming, which is a good way to judge the fit before committing to a version bump.

Editorial conclusion

Adopt bslib if you are building a Shiny app or R Markdown document and want modern Bootstrap components and live theming rather than the default look. Skip it if your app is already written against Bootstrap 3 conventions, since the package keeps those defaults for backwards compatibility and switching changes the layout. Before you commit, run bslib::bs_theme_preview() to see the component set in a real app, and check whether the Shiny version you are on accepts the bslib theming, because the package is meant to sit underneath Shiny rather than replace it.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. rstudio/bslib on GitHub