Skip to content

Commit e080bf7

Browse files
tmorehousetmorehouse
authored
feat(docs): updates to the theming reference section (#3790)
1 parent 2cdb493 commit e080bf7

File tree

2 files changed

+180
-9
lines changed

2 files changed

+180
-9
lines changed

‎docs/markdown/reference/theming/README.md‎

Lines changed: 174 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,108 @@ stacked tables, etc). Our custom CSS relies on variables defined the Bootstrap v
99
source SCSS, you can have your variable overrides (such as breakpoints, etc) adjust the custom
1010
BootstrapVue css.
1111

12-
## Custom SCSS
12+
## SASS variable defaults
1313

14-
To use your own theme and colors in `bootstrap-vue`, you will need to create a `custom.scss` file in
14+
Every Sass variable in Bootstrap 4 includes the `!default` flag allowing you to override the
15+
variable’s default value in your own Sass without modifying Bootstrap’s source code. Copy and paste
16+
variables as needed, modify their values, and remove the `!default` flag. If a variable has already
17+
been assigned, then it won’t be re-assigned by the default values in Bootstrap.
18+
19+
You will find the complete list of Bootstrap’s variables in `bootstrap/scss/_variables.scss`. Some
20+
variables are set to `null`, these variables don’t output the property unless they are overridden in
21+
your configuration.
22+
23+
Variable overrides within the same Sass file can come before or after the default variables.
24+
However, when overriding across Sass files, your overrides must come _before_ you import Bootstrap’s
25+
Sass files.
26+
27+
Here’s an example that changes the `background-color` and `color` for the `<body>` when importing
28+
and compiling Bootstrap SCSS:
29+
30+
```scss
31+
// Your variable overrides
32+
$body-bg: #000;
33+
$body-color: #111;
34+
35+
// Bootstrap and its default variables
36+
@import '../node_modules/bootstrap/scss/bootstrap';
37+
// BootstrapVue and its default variables
38+
@import '../node_modules/bootstrap-vue/src/index.scss';
39+
```
40+
41+
## Default theme colors
42+
43+
The default them colors defined in the Bootstrap v4.3 SCSS are as follows:
44+
45+
<div class="row">
46+
<div class="col-md-4">
47+
<div class="p-3 mb-3 bg-primary text-light">Primary</div>
48+
</div>
49+
<div class="col-md-4">
50+
<div class="p-3 mb-3 bg-secondary text-light">Secondary</div>
51+
</div>
52+
<div class="col-md-4">
53+
<div class="p-3 mb-3 bg-success text-light">Success</div>
54+
</div>
55+
<div class="col-md-4">
56+
<div class="p-3 mb-3 bg-danger text-light">Danger</div>
57+
</div>
58+
<div class="col-md-4">
59+
<div class="p-3 mb-3 bg-warning text-dark">Warning</div>
60+
</div>
61+
<div class="col-md-4">
62+
<div class="p-3 mb-3 bg-info text-light">Info</div>
63+
</div>
64+
<div class="col-md-4">
65+
<div class="p-3 mb-3 bg-light text-dark">Light</div>
66+
</div>
67+
<div class="col-md-4">
68+
<div class="p-3 mb-3 bg-dark text-light">Dark</div>
69+
</div>
70+
</div>
71+
72+
Various components will use variations (intensities) of these default theme colors.
73+
74+
You can alter the theme colors, and create additional theme colors, as needed via SASS variables and
75+
maps. Refer to the [Bootstrap theming](https://getbootstrap.com/docs/4.3/getting-started/theming/)
76+
docs for more details. All theme colors automatically become available as
77+
[color variants](/docs/reference/color-variants) to all BootstrapVue components.
78+
79+
## SASS options
80+
81+
Customize Bootstrap 4 with the built-in custom variables file and easily toggle global CSS
82+
preferences with Bootstrap's `$enable-*` Sass variables.
83+
84+
Some commonly used Bootstrap v4 variables are:
85+
86+
| Variable | Type | Default | Description |
87+
| ------------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------ |
88+
| `$enable-rounded` | Boolean | `true` | Enables predefined `border-radius` styles on various components |
89+
| `$enable-shadows` | Boolean | `false` | Enables predefined `box-shadow` styles on various components |
90+
| `$enable-gradients` | Boolean | `false` | Enables predefined gradients via `background-image` styles on various components |
91+
| `$enable-transitions` | Boolean | `true` | Enables predefined `transition`s on various components |
92+
| `$enable-responsive-font-sizes` | Boolean | `false` | Enables [responsive font sizes](https://getbootstrap.com/docs/4.3/content/typography/#responsive-font-sizes) |
93+
| `$enable-validation-icons` | Boolean | `true` | Enables `background-image` icons within textual inputs and some custom forms for validation states |
94+
95+
Refer to [Bootstrap's theming](https://getbootstrap.com/docs/4.3/getting-started/theming/) docs for
96+
additional variable information.
97+
98+
BootstrapVue also defines several SCSS variables for controlling BootstrapVue's custom CSS
99+
generation:
100+
101+
| Variable | Type | Default | Description |
102+
| ----------------------------- | ------- | ------- | -------------------------------------- |
103+
| `$bv-enable-table-stacked` | Boolean | `true` | Enables stacked table CSS generation |
104+
| `$bv-enable-tooltip-variants` | Boolean | `true` | Enables tooltip variant CSS generation |
105+
| `$bv-enable-popover-variants` | Boolean | `true` | Enables popover variant CSS generation |
106+
107+
You can find additional variables that control various aspects of BootstrapVue's custom CSS at
108+
[`bootstrap-vue/src/_variables.scss`](https://github.com/bootstrap-vue/bootstrap-vue/blob/master/src/_variables.scss).
109+
BootstrapVue's custom SCSS relies on Bootstrap's SASS variables, functions, and mixins.
110+
111+
## Generating custom themes
112+
113+
To use your own theme and colors in BootstrapVue, you will need to create a `custom.scss` file in
15114
your project, which you can include in your main app:
16115

17116
**Via template:**
@@ -31,7 +130,7 @@ your project, which you can include in your main app:
31130
32131
**Via app main entry point:**
33132
34-
Create a SCSS file:
133+
Create an SCSS file:
35134
36135
```scss
37136
// custom.scss
@@ -59,7 +158,7 @@ Then import that single SCSS file into your app code entry point:
59158
import 'custom.scss'
60159
```
61160
62-
The `_custom.scss` file, which needs to be loaded before Bootstrap's SCSS, will include your
161+
The `custom.scss` file, which needs to be loaded before Bootstrap's SCSS, will include your
63162
Bootstrap v4 variable overrides (i.e. colors, shadows, font sizes, breakpoints, etc). You can find
64163
all of the possible variables in `node_modules/bootstrap/scss/_variables.scss`.
65164
@@ -71,6 +170,77 @@ npm install --save-dev node-sass sass-loader
71170
72171
**Note:** You may need to adjust the SCSS import paths based on your build environment.
73172
173+
## CSS variables
174+
175+
Bootstrap's SCSS generates around two dozen
176+
[CSS custom properties (variables)](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables)
177+
in the compiled CSS. These provide easy access to commonly used values like theme colors,
178+
breakpoints, and primary font stacks when working in your browser’s Inspector, a code sandbox, or
179+
general prototyping.
180+
181+
### Available Bootstrap CSS variables
182+
183+
Here are the variables that are generated. The values shown are based on the Bootstrap v4 defaults:
184+
185+
```scss
186+
:root {
187+
--blue: #007bff;
188+
--indigo: #6610f2;
189+
--purple: #6f42c1;
190+
--pink: #e83e8c;
191+
--red: #dc3545;
192+
--orange: #fd7e14;
193+
--yellow: #ffc107;
194+
--green: #28a745;
195+
--teal: #20c997;
196+
--cyan: #17a2b8;
197+
--white: #fff;
198+
--gray: #6c757d;
199+
--gray-dark: #343a40;
200+
--primary: #007bff;
201+
--secondary: #6c757d;
202+
--success: #28a745;
203+
--info: #17a2b8;
204+
--warning: #ffc107;
205+
--danger: #dc3545;
206+
--light: #f8f9fa;
207+
--dark: #343a40;
208+
--breakpoint-xs: 0;
209+
--breakpoint-sm: 576px;
210+
--breakpoint-md: 768px;
211+
--breakpoint-lg: 992px;
212+
--breakpoint-xl: 1200px;
213+
--font-family-sans-serif: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue',
214+
Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';
215+
--font-family-monospace: SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono',
216+
'Courier New', monospace;
217+
}
218+
```
219+
220+
By setting SASS variables and maps, and recompiling the SCSS, will update the above generated CSS
221+
variables.
222+
223+
### Example
224+
225+
CSS variables offer similar flexibility to SASS’s variables, but without the need for compilation
226+
before being served to the browser. For example, here we are resetting our page’s font and link
227+
styles, as well as creating a custom class that uses theme colors, via the use of CSS variables.
228+
229+
```scss
230+
body {
231+
font: 1rem/1.5 var(--font-family-sans-serif);
232+
}
233+
234+
a {
235+
color: var(--blue);
236+
}
237+
238+
.custom-class {
239+
color: var(--primary);
240+
background-color: var(--dark);
241+
}
242+
```
243+
74244
## See also
75245
76246
- If you are defining custom breakpoint names, please see the

‎docs/pages/index.vue‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<main id="content" role="main">
33
<section class="bd-masthead pt-3 pt-sm-5 pb-2">
44
<b-container tag="article">
5-
<b-row align-v="center" no-gutters class="mb-4">
5+
<b-row align-v="center" no-gutters class="mb-2 mb-md-3 mb-lg-4">
66
<!-- eslint-disable-next-line vue/max-attributes-per-line -->
77
<b-col tag="aside" cols="12" md="4" order-md="2" class="logo-aside mb-4 mb-md-0">
88
<svg
@@ -115,12 +115,13 @@
115115
is a progressive framework for building user interfaces.
116116
</b-media-body>
117117
</b-media>
118-
119-
<p class="mb-0 text-muted">
120-
Currently <b-link to="/docs/misc/changelog">v{{ version }}</b-link>
121-
</p>
122118
</b-col>
123119
</b-row>
120+
121+
<p class="mb-0 text-muted text-center mb-n4 mb-md-n5">
122+
Current Version<br>
123+
<b-link to="/docs/misc/changelog" class="small">v{{ version }}</b-link>
124+
</p>
124125
</b-container>
125126
</section>
126127

0 commit comments

Comments
 (0)