forked from rstudio/bslib
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
168 lines (127 loc) · 5.63 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
---
output: github_document
---
<!-- badges: start -->
[](https://cran.r-project.org/package=bslib) [](https://www.tidyverse.org/lifecycle/#experimental) [](https://github.com/rstudio/bslib/actions)
<!-- badges: end -->
```{r, include = FALSE}
knitr::opts_chunk$set(
message = FALSE,
collapse = TRUE,
comment = "#>",
fig.align = "center"
)
library(bslib)
```
# bslib (formerly known as bootstraplib)
The `{bslib}` R package provides tools for creating custom [Bootstrap themes](https://getbootstrap.com/docs/4.4/getting-started/theming/), making it easier to style Shiny apps & R Markdown documents directly from R without writing unruly CSS and HTML. At the moment, `{bslib}` provides special builds of Bootstrap 4 & 3 that "just work" with Shiny & R Markdown.
## Installation
`{bslib}` isn't yet available from CRAN, but you can install with:
``` r
remotes::install_github("rstudio/bslib")
```
## Getting Started
### Create a theme
Use `bs_theme()` to create a `{bslib}` theme, where you can:
- Choose a (major) Bootstrap version (e.g., `version = 4` or `version = 3`).
- If `version` isn't specified (as in the example below), then `version` defaults to `version_default()`, which may change to Bootstrap 5 in a future version of `{bslib}`.
- Choose a [Bootswatch](https://bootswatch.com/) theme (e.g., `bootswatch = 'darkly'`).
- Customize the main colors and fonts (e.g., `bg`, `fg`, `primary`, `base_font`, etc)
- These main controls are available via named arguments to `bs_theme()` (and `bs_theme_update()`) and are guaranteed to work across Bootstrap versions.
- More generally, customize most of Bootstrap's styling via Sass variables (e.g., [`font-size-base`](https://github.com/rstudio/bslib/blob/c353705/inst/lib/bootstrap/scss/_variables.scss#L282)).
- These more specific controls pass through the `...` of `bs_theme()`.
- These options likely depend on the Bootstrap version being used
For example, to implement a [material design inspired dark mode](https://material.io/design/color/dark-theme.html):
``` r
library(bslib)
my_theme <- bs_theme(
bg = "#202123", fg = "#B8BCC2", primary = "#EA80FC",
base_font = font_google("Grandstander"),
"font-size-base" = "1.1rem"
)
```
### Shiny usage
> Note: this usage requires the development version of Shiny `remotes::install_github("rstudio/shiny")`.
To use `my_theme` inside of Shiny, pass it to the relevant `theme` parameter in page functions such as `shiny::navbarPage()`, `shiny::fluidPage()`, `shiny::bootstrapPage()`, etc.
``` r
library(shiny)
ui <- navbarPage(
theme = my_theme,
...
)
shinyApp(ui, function(input, output) {})
```
For a preview of how `my_theme` impacts most of Shiny UI's styling defaults, provide it to `bs_theme_preview()`. This preview app includes most "core" Shiny UI functionality as well as an interactive "real-time" theming widget for quickly testing out new colors and fonts. To help replicate those styling changes, the widgets also emits code to the R console. It can also be used with other Shiny apps via `run_with_themer()` (or `bs_themer()`).
``` r
bs_theme_preview(my_theme)
```
```{r, echo = FALSE}
knitr::include_graphics("https://i.imgur.com/KLKy1s0.gif")
```
More generally, you can use a Bootstrap theme with any HTML page by using `shiny::bootstrapLib()` to provide the theme as an `htmltools::htmlDependency()` to an `shiny::htmlTemplate()` or any HTML `htmltools::tags` that you wish, for example:
``` r
library(shiny)
ui <- htmlTemplate(
"my-template.html",
theme = my_theme,
...
)
shinyApp(ui, function(input, output) {})
```
``` html
<!-- my-template.html -->
<!DOCTYPE html>
<html>
<head>
{{ headContent() }}
{{ bootstrapLib(theme) }}
</head>
<body>
...
</body>
</html>
```
### R Markdown usage
> Note: this usage currently requires an experimental version of R Markdown `remotes::install_github("rstudio/rmarkdown#1706")`
To use a `bs_theme()` in R Markdown, pass the relevant theming parameter(s) to the `theme` parameter of `html_document` (or, really, anything that runs through `html_document_base`):
``` yaml
---
output:
html_document:
theme:
bg: "#202123"
fg: "#B8BCC2"
primary: "#EA80FC"
base_font: !expr bslib::font_google("Grandstander")
---
```
At the moment, `{bslib}` is a opt-in feature in R Markdown (i.e., whenever `theme` is a list or a `bs_theme()`, then `{bslib}` is used). This means that, to use the default `bslib::bs_theme()`:
``` yaml
---
output:
html_document:
theme: !expr bslib::bs_theme()
---
```
Moreover, when opting into `{bslib}`, you may modify `theme` object globally inside **knitr** code chunks. This can be useful for things like adding additional CSS rules that leverage Bootstrap Sass variables, functions, mixins, etc:
```{r}`r ''`
library(bslib)
bs_global_add_rules(
".my-class {
background-color: mix($body-bg, $body-color, 90%);
border: 1px solid $primary;
@include border_radius($border-radius);
}
"
)
```
### Add to a theme
`bs_theme()` customizes Bootstrap CSS by changing Bootstrap Sass variable defaults, but sometimes you need to customize the theme in other ways by adding other Sass code. For example, if you'd like to add Sass/CSS rules for a custom, themable, component:
```r
my_theme %>%
bs_add_rules(
".my-component { color: $primary; }"
)
```
## Learn more
To learn more, see the [theming article](https://rstudio.github.io/bslib/articles/theming.html).