Usage
teal app developers can specify custom Bootstrap themes
by setting the teal.bs_theme R option, which
has to be set to bslib::bs_theme object. The
bslib::bs_theme(...) function creates a Bootstrap theme
object, where one specifies the (major) Bootstrap version (default or
one of 3, 4, or 5). Optionally one can choose a
bootswatch theme and customize the
app CSS with functions like bslib::bs_add_rules.
Please read more about custom themes in the
bslib getting started vignette. The
teal.bs_theme R option has to be specified at
the top of the code script.
Please install bslib package before you run the code
below.
teal.bs_theme R option
options("teal.bs_theme" = bslib::bs_theme("Custom Options"))
#######################
# teal::init() app code
#######################Bootstrap version and themes
The best and recommended ways to explore the
Bootstrap themes are to use
bslib::run_with_themer(shinyApp(app$ui, app$server)) or
bslib::bs_theme_preview(), both of which offer an
interactive explore mode (not supported for Bootstrap 3). The
bslib::bs_theme_preview() is recommended when the end user
does not have any shiny app yet. When you already have a
shiny app and you want to test different Bootstrap themes
(and CSS styling) then
bslib::run_with_themer(shinyApp(app$ui, app$server)) is
recommended.
Available Bootstrap versions could be checked with
bslib::versions() and Bootstrap themes
(bootswatch) with
bslib::bootswatch_themes(version = "5").
# bslib::versions()
# bslib::bootswatch_themes(version = "5")
options("teal.bs_theme" = bslib::bs_theme(version = "5", bootswatch = "lux")
# or
options("teal.bs_theme" = bslib::bs_theme_update(bslib::bs_theme(version = "5"), bootswatch = "lux"))Default Bootstrap theme
When using the default bslib theme for any version (3, 4
or 5), its styling might not be as expected. Please run the interactive
themer (recommended) or apply a custom theme to explore all the theme
options. In many scenarios updating only the theme might not be
enough and e.g. font color and other specifications should be updated
too.
# instead of
options("teal.bs_theme" = bslib::bs_theme(version = "5"))
# try non-default themes
options("teal.bs_theme" = bslib::bs_theme(version = "5", bootswatch = "THEME NAME". ...))
# or run the app inside bslib::run_with_themerReset the Bootstrap theme
Please use the options("teal.bs_theme" = NULL) call to
return to the default shiny Bootstrap for teal
apps.
Theme not updated
One reason the theme is not updated could be that the web browser
caches the previous one, especially when different themes are run one
after another. Please, use the Cmd+Shift+R (Mac) or
Ctrl+F5 (Windows) to hard refresh the webpage.
Custom teal CSS
The most important HTML tags in teal have a specific id
or class, so they can be directly styled. The
bslib::bs_add_rules function could be used around the
bslib::bs_theme object to apply custom CSS
rules.
library(magrittr)
options("teal.bs_theme" = bslib::bs_theme(version = "5") %>% bslib::bs_add_rules("Anything understood by sass::as_sass()"))Other bslib::bs_add_* family functions could be used to
specify low-level Bootstrap elements.
Bootstrap NULL vs Bootstrap 3
It is important to note that the statements
options("teal.bs_theme" = NULL) and
options("teal.bs_theme" = bslib::bs_theme(version = "3")
are not equivalent as the bslib approximation of the
default shiny theme for Bootstrap version 3 can introduce
some discrepancies. One important difference is that when using
bslib::bs_theme(version = "3", bootswatch = "THEME NAME")
one can apply the custom Bootstrap theme. Another one is that the usage
of bslib::bs_theme(version = "3") requires the installation
of the latest shinyWidgets package from the main branch,
see below.
# Downloading the newest shinyWidgets
# needed only when bslib::bs_theme(version = "3", ...) is used
remotes::install_github("https://github.com/dreamRs/shinyWidgets@main")Regular shiny::fluidPage
If you want to update the theme in a regular
shiny::fluidPage-like app, you do not need the
teal.bs_theme option. Simply provide the
bslib::bs_theme directly:
shiny::fluidPage(theme = bslib::bs_theme(...), ...).
Interactive theming guide
In this section we provide a step-by-step guide to customizing a
teal application theme interactively with
bslib::run_with_themer(). We recommend starting with a
simple case and once you are satisfied, verifying with your full
application. To that end we will use the teal application
below. For this example we assume that we want to use Bootstrap 5. To
start, we launch the app with
bslib::run_with_themer(app$ui, app$server) instead of
shiny::shinyApp.
options("teal.bs_theme" = bslib::bs_theme(version = "5"))
library(teal)
app <- init(
data = teal_data(IRIS = iris),
filter = teal_slices(teal_slice("IRIS", "Sepal.Length", selected = c(5, 7))),
modules = modules(example_module(), example_module()),
header = "My first teal application"
)
bslib::run_with_themer(shinyApp(app$ui, app$server))This gives us the following.
Note the Theme Customizer section on the right hand
side. This was added by bslib and is how we customize our
theme.
Set overall app theme
Instead of starting from scratch, we want to start with a Bootswatch theme. Let us
select the Minty theme in the “Overall theme” drop-down.
bslib has updated our CSS styles to use our
new theme, including the customizer theme. Additionally, if
we look at our R console, we will see
#### Update your bs_theme() R code with: #####
bs_theme_update(theme, bootswatch = "minty")This is a helpful guide that provides code to update our theme. For
teal applications we don’t actually use
bs_theme_update and opt for bs_theme instead.
However, the printed code will still be helpful.
Customize a bootswatch theme
Our base theme (Minty) is close to what we want but let’s make a few
modifications. To start, we will increase the base font size. To do
this, we choose the “Fonts” section of the customizer theme
and then set a value in the “Base font size” input. We use 1.25 here,
which means all our fonts will be increased by a factor of 1.25. If we
check the R console, we will see bslib has
printed
bs_theme_update(theme, font_scale = 1.25, bootswatch = "minty"),
which now includes our font size adjustment.
Finally, suppose we do not want borders to be rounded. In our
customizer theme, we can go to “Options” and then uncheck
the “Rounded corners” box.
As expected, our corners are no longer rounded. If we look at our
R console, we will now see
bs_theme_update(theme, font_scale = 1.25,enable-rounded= FALSE, bootswatch = "minty").
Apply the customized theme
Once our customization is complete, we will apply the changes to our
application. To do this, we use the option teal.bs_theme
like before but this time we will expand on our
bslib::bs_theme call to include our changes. Luckily, the
arguments that were printed to the R console when running
our app in the themer can be plugged right in.
options(
"teal.bs_theme" = bslib::bs_theme(
version = "5",
font_scale = 1.25,
`enable-rounded` = FALSE,
bootswatch = "minty"
)
)
library(teal)
app <- init(
data = teal_data(IRIS = iris),
filter = teal_slices(teal_slice("IRIS", "Sepal.Length", selected = c(5, 7))),
modules = modules(example_module(), example_module())
)
shinyApp(app$ui, app$server)Now the application has our custom theme applied.
Please note the interactive themer only contains the most commonly
applied options. For more customization options, review the
bslib documentation.