- Auto theming can also work with rmarkdown::htmldocument.The main catch is that, if R plots are not generated via Shiny, then any custom styling must be done via the bslib package in order for thematic to know about it. In the example below, we set a custom background, foreground, and accent color via bslib; then use thematicrmd to apply automatic coloring to every R plot.
- I try to have a Markdown document with a verbose option (i.e. Show or not the code of the page, to avoid to afraid people:D ) depending on the choice of the user (basically a radio button widget).
- Shiny, R Markdown, Tidyverse and more. Hosted Services Be our guest, be our guest. Do, share, teach and learn data science. RStudio Public Package Manager. An easy way to access R packages. Let us host your Shiny applications. Professional Enterprise-ready.
This is an introduction to the basic features of R Markdown, and R Markdown Playground Application as part of the book on Statistical Programming used as a s. Shiny is an R package that makes it easy to build interactive web apps straight from R. You can host standalone apps on a webpage or embed them in R Markdown documents or build dashboards. You can also extend your Shiny apps with CSS themes, htmlwidgets, and JavaScript actions.
The
bslib
R package provides tools for customizing Bootstrap themes directly from R, making it much easier to customize the appearance of Shiny apps & R Markdown documents. bslib
’s primary goals are:- Make custom theming as easy as possible.
- Custom themes may even be created interactively in real-time.
- Also provide easy access to pre-packaged Bootswatch themes.
- Make upgrading from Bootstrap 3 to 4 (and beyond) as seamless as possible.
- Shiny and R Markdown default to Bootstrap 3 and will continue to do so to avoid breaking legacy code.
- Serve as a general foundation for Shiny and R Markdown extension packages.
- Extensions such as
flexdashboard
,pkgdown
, andbookdown
already fully supportbslib
’s custom theming capabilities.
- Extensions such as
Installation
Install the stable release of
bslib
on CRAN:Usage with Shiny requires version 1.6 or higher:
Onenote and microsoft teams. Usage with R Markdown requires version 2.7 or higher:
Basic usage
bslib
is designed for use with any Shiny or R Markdown project that uses Bootstrap. In most cases, you can identify a project that uses Bootstrap when the relevant page constructor has a theme
parameter. For example, most Shiny page layout functions (e.g., shiny::navbarPage()
) and some popular R Markdown formats (e.g., rmarkdown::html_document
) all have a theme
parameter.To use
bslib
in Shiny, provide a bs_theme()
object to the theme
parameter; and in R Markdown, provide bs_theme()
parameters to theme
. For example, here’s a way to upgrade Shiny (left) and R Markdown (right) from Bootstrap 3 to 4:See the Get Started article to learn more about Bootstrap versions, pre-packaged Bootswatch themes, (real-time) custom theming, and more.
To get started more quickly, choose a relevant R Markdown template from inside RStudio by going to File -> New File -> R Markdown -> From Template:
Getting help
There are two main places to get help with
bslib
:- The RStudio community is a friendly place to ask any questions about flexdashboard. Be sure to use the
bslib
tag. Add also theshiny
tag is you are using a Shiny runtime.DYMO Software compatibility issues with Microsoft Windows Update. Current status: issues with printing blank labels from our software, due to latest Windows update, have been resolved. What’s required: update your software for DYMO Connect, DYMO Label Software, or Dymo ID (XTL). Once you have found the correct printer software on the Dymo Website, go ahead and download it. Dymo label printer 400 software. - Stack Overflow is a great source of answers to common
bslib
questions. It is also a great place to get help, once you have created a reproducible example that illustrates your problem. Use the tags[r][bslib]
if you ask a question. Add the tag[bslib]
if you are using a Shiny runtime.
Code of Conduct
Please note that the bslib project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.
2021-04-08
Source:vignettes/auto.Rmd
The most magical aspect of thematic is its auto theming capabilities, which gives R plots to ability to style themselves in Shiny (via CSS), R Markdown (via bslib), and RStudio (via RStudio themes). To gain a sense for how auto theming works, it’s recommended you read through the next section, which walks through several variants on a basic Shiny app, and demonstrates how auto theming makes R plots responsive to changes in CSS styling. Also, as discussed in other scenarios, it possible to configure the information thematic uses for auto theming, but you can also opt-out of auto theming by providing desired colors and fonts to thematic (as discussed on custom themes).
Shiny
One frustrating thing about styling Shiny apps is that R plots know nothing about CSS. That means, if you write custom CSS to style the app, you’ll likely also want to translate those same styles to the R graphics. You may have never noticed this problem before if you just use the default styles in both systems because they’re quite similar. Here’s the default styles in a Shiny app with a few R plots inside a
tabsetPanel()
:By bringing in a new set of CSS rules, say the darklyshinytheme, the difference in CSS vs R styles becomes much more apparent:
By activating thematic auto coloring (as shown below), R plot(s) generated by the Shiny app gain new color defaults based on the surrounding CSS styles. This works because, at plot time, thematic grabs CSS styles from the plot(s) HTML container (via
shiny::getCurrentOutputInfo()
)1 and uses that info to set new R styling defaults.From the ggplot2 example above, we can see
thematic_shiny()
has done the following for us:- Set new
ggplot2::theme()
-ing defaults based on the background and foreground colors (as well as appropriate mixtures of these colors for the panel background). - Set a new color-blind safe default for
scale_color_discrete()
(andscale_fill_discrete()
).
Now, if we change our
tabsetPanel()
from type='pills'
to type='tabs'
and look at a couple other ggplot2 examples, we can see that thematic_shiny()
does a few more things:![R shiny markdown output R shiny markdown output](/uploads/1/3/4/7/134785728/394447569.png)
- Sets new
geom_*()
defaults using the new foreground (in this case,geom_point()
’scolor
) and accent color (in this case,geom_smooth()
’s color).- The accent color comes from the hyperlink color of the plot’s HTML container. It just so happens that this darkly theme colors
type='tabs'
the same as hyperlinks, buttype='pills'
is colored differently.
- The accent color comes from the hyperlink color of the plot’s HTML container. It just so happens that this darkly theme colors
Also:
- Uses the background, foreground, and accent colors to construct a new default for
scale_fill_continuous()
(andscale_color_continuous()
).
As you’ll learn in the custom themes article, you can always override the defaults set by thematic by using plot-specific code (i.e., by adding
theme()
elements to the plot). However, if you want to use a different completeggplot2 theme (e.g., theme_minimal()
instead of the default theme_gray()
), you should set the theme globally with ggplot2::theme_set()
.Since thematic knows the CSS rules on the plot’s HTML container, auto theming works regardless of how the HTML is actually styled. That said, consider using the new bslib package to theme your Shiny apps (and R Markdown docs). It provides a rich set of tools for influencing Bootstrap CSS from R, including convenience functions for setting the main colors and fonts:
As shown in the image above, text rendered by the browser (i.e.,
tabsetPanel()
’s titles) now uses the Pacifico font, but the R plots are still using the default font because, by default, thematic_shiny()
only enables automatic colors. To enable auto fonts, set font = 'auto'
; and when doing so, make sure the font to be rendered is either a font already supported by R, or is Google Font and the showtext package is installed (learn more in the fonts article).thematic also works great with bslib’s realtime theming widget. This interactive widget influences the CSS on the page, so as long as thematic’s auto theming enabled, those CSS changes automatically influence the R plot styling. Note how here we still have both auto fonts and colors, which means that as long as we choose Google Fonts (and/or fonts already known to R), the R plots can automatically render them.
R Markdown
Auto theming can also work with
rmarkdown::html_document()
. The main catch is that, if R plots are not generated via Shiny, then any custom styling must be done via the bslib package in order for thematic to know about it. In the example below, we set a custom background, foreground, and accent color via bslib; then use thematic_rmd()
to apply automatic coloring to every R plot generated in the R Markdown document.Auto theming doesn’t necessarily work for non-HTML output formats. In that case, provide the document’s colors and fonts either directly to
thematic_rmd()
or to auto_config()
. To learn more about various options forRStudio
Here’s a ggplot2 plot inside the RStudio IDE before thematic is enabled. Note the colors in the IDE are based on the Tomorrow Night 80s RStudio Theme and the editor’s font is FiraCode.
After calling
thematic_on(font = 'Fira Sans Condensed')
to enable automatic colors and request the Fira Sans Condensed Google Font, the colors in the Plots viewer pane now match the RStudio theme2, and the fonts nicely complement the editor’s font.By the way, rendering of Google Fonts in RStudio requires a special setup that’s discussed in the fonts article.
Other scenarios
How To Use R Markdown
As the R Markdown section already eluded to (in reference to non-HTML output formats), thematic’s auto theming won’t know what styles to use in every scenario. In these scenarios, you have the following options:
R Shiny And Markdown
- Avoid
'auto'
values entirely by providing the desired colors and fonts directly tothematic_on()
. The next article, Custom Themes, discusses this option in depth. - Allow auto theming to “fail”, meaning that thematic effectively has no effect on the visual output.
- Use
auto_config()
andauto_config_set()
to set “fallbacks” for'auto'
values. For example:
The main use case for
auto_config()
is for developers of a custom rmarkdown output document that wish to provide an auto theming experience for users of the document (see auto_config()
for more details). However, there may also be scenarios where more control over the set and priority of information that auto_resolve_theme()
uses to resolve 'auto'
values. This can be done via the priority
argument of auto_config()
. The default priority
is:shiny::getCurrentOutputInfo()
('shiny'
)auto_config_get()
('config'
)bslib::bs_get_variables()
('bslib'
)rstudioapi::getThemeInfo()
('rstudio'
)
- If you’re a shiny developer and wish to add similar auto theming capabilities to a custom output, you can add a
.shiny-report-theme
class to the output container to obtain styles viagetCurrentOutputInfo()
. And similarly, if you’re an htmlwidgets developer, you can just setreportTheme = TRUE
inhtmlwidgets::shinyWidgetOutput()
.↩︎ - Auto detection of background and foreground should always work in RStudio, but
accent='auto'
is currently limited to non-custom RStudio themes. Moreover,font='auto'
is fully supported on RStudio Server Pro (1.4 or higher), but may not work on RStudio Desktop.↩︎