rooty/Bootstrap
0
0
Fork 0
mirror of https://github.com/twbs/bootstrap.git synced 2025-02-26 23:54:23 +01:00
Code Issues Actions Packages Releases Activity

Reorganise headings in utilities page and minor edits

Browse Source
This commit is contained in:
Romaric Pascal 2022-03-16 14:39:12 +00:00
parent 4b06819ac2
commit c0ac568ff6
1 changed files with 116 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

189
site/content/docs/5.3/utilities/api.md
View File

@ -369,16 +369,27 @@ All utilities generated by the API include `!important` to ensure they override
Now that you're familiar with how the utilities API works, learn how to add your own custom classes and modify our default utilities. There are two ways you can do this:
1. If you only need to override our default utilities or add new ones, we'll merge your `$utilities` variable with ours
2. If you require more fine grained control, we provide mixins to let you update our default utilities configuration.
2. If you require more fine-grained control, we provide mixins to let you update our default utilities configuration.
You may also want to refer to some of the utilities configuration in your Sass code, for which we provide some handy functions.
You may also want to refer to parts of the utilities configuration in your Sass code, the value of a specific utility especially. We provide getter functions to access those.
### Adding or overriding utilities
Override existing utilities by using the same key. For example, if you want additional responsive overflow utility classes, you can do this:
If your code declares a `$utilities` map before importing `bootstrap/scss/utilities`,
it'll get merged with ours:
- add new keys to create your own utilities
- override existing utilities by using the same key
```scss
$utilities: (
// Adds a new font-variant utility
"font-variant": (
class: fv,
property: font-variant,
values: tabular-nums small-caps,
),
// Redefines the overflow utility
"overflow": (
responsive: true,
property: overflow,
@ -487,76 +498,7 @@ replacing the `values` option can be a bit of a burden to maintain.
@import 'bootstrap/scss/utilities/api';
```
#### Practical examples
##### Enable responsive
You can enable responsive classes for an existing set of utilities that are not currently responsive by default. For example, to make the `border` classes responsive:
```scss
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";
@include utilities-set-option(border, responsive, true);
@import "bootstrap/scss/utilities/api";
```
##### Rename utilities
Missing v4 utilities, or used to another naming convention? The utilities API can be used to override the resulting `class` of a given utility—for example, to rename `.ms-*` utilities to oldish `.ml-*`:
```scss
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";
@include utilities-set-option(margin-start, class, ml);
@import "bootstrap/scss/utilities/api";
```
##### Remove utility in RTL
Some edge cases make [RTL styling difficult](https://rtlstyling.com/posts/rtl-styling#common-things-that-might-not-work-for-rtl), such as line breaks in Arabic. Thus utilities can be dropped from RTL output by setting the `rtl` option to `false`:
```scss
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";
@include utilities-set-option(word-wrap, rtl, false);
@import "bootstrap/scss/utilities/api";
```
Output:
```css
/* rtl:begin:remove */
.text-break {
word-wrap: break-word !important;
word-break: break-word !important;
}
/* rtl:end:remove */
```
This doesn't output anything in RTL, thanks to [the RTLCSS `remove` control directive](https://rtlcss.com/learn/usage-guide/control-directives/#remove).
### Referring to the utilities configuration
### Getting utility values and options
The `utilities-get-value` function let your grab a specific value of a utility.
This can help you run some computations with it, either in Sass or with `calc()`.
@ -586,3 +528,104 @@ This is likely the function you'll use the most, but you can also:
- access all the values of a utility with `utilities-get-values`, which will always return a map to simplify their processing
- access a specific option with `utilities-get-option`
- or even all the options with `utilities-get-options`
## Practical examples
### Enable responsive
You can enable responsive classes for an existing set of utilities that are not currently responsive by default. For example, to make the `border` classes responsive:
```scss
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";
@include utilities-set-option(border, responsive, true);
@import "bootstrap/scss/utilities/api";
```
This will now generate responsive variations of `.border` and `.border-0` for each breakpoint. Your generated CSS will look like this:
```css
.border { ... }
.border-0 { ... }
@media (min-width: 576px) {
.border-sm { ... }
.border-sm-0 { ... }
}
@media (min-width: 768px) {
.border-md { ... }
.border-md-0 { ... }
}
@media (min-width: 992px) {
.border-lg { ... }
.border-lg-0 { ... }
}
@media (min-width: 1200px) {
.border-xl { ... }
.border-xl-0 { ... }
}
@media (min-width: 1400px) {
.border-xxl { ... }
.border-xxl-0 { ... }
}
```
### Rename utilities
Missing v4 utilities, or used to another naming convention? The utilities API can be used to override the resulting `class` of a given utility—for example, to rename `.ms-*` utilities to oldish `.ml-*`:
```scss
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";
@include utilities-set-option(margin-start, class, ml);
@import "bootstrap/scss/utilities/api";
```
### Remove utility in RTL
Some edge cases make [RTL styling difficult](https://rtlstyling.com/posts/rtl-styling#common-things-that-might-not-work-for-rtl), such as line breaks in Arabic. Thus utilities can be dropped from RTL output by setting the `rtl` option to `false`:
```scss
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";
@include utilities-set-option(word-wrap, rtl, false);
@import "bootstrap/scss/utilities/api";
```
Output:
```css
/* rtl:begin:remove */
.text-break {
word-wrap: break-word !important;
word-break: break-word !important;
}
/* rtl:end:remove */
```
This doesn't output anything in RTL, thanks to [the RTLCSS `remove` control directive](https://rtlcss.com/learn/usage-guide/control-directives/#remove).