root
/
bootstrap
mirror of https://github.com/twbs/bootstrap.git
1
0
Fork 0
Code Issues Actions 11 Packages Projects Releases Wiki Activity

Editing and formatting utilities API page

This commit is contained in:
Mark Otto 2020-11-02 19:03:15 +02:00 committed by XhmikosR
parent 366b841f4f
commit 3b985977c9
1 changed files with 81 additions and 160 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

239
site/content/docs/5.0/utilities/api.md
View File

@ -7,21 +7,24 @@ aliases: "/docs/5.0/utilities/"
toc: true toc: true
--- ---
The bootstrap utilities are generated with the utility API which can be used to change or extend Bootstrap's utility classes. If you don't have any idea what Sass maps are, you can consult the [official docs](https://sass-lang.com/documentation/values/maps) to get started. Bootstrap utilities are generated with our utility API and can be used to modify or extend our default set of utility classes via Sass. Our utility API is based on a series of Sass maps and functions for generating families of classes with various options. If you're unfamiliar with Sass maps, read up on the [official Sass docs](https://sass-lang.com/documentation/values/maps) to get started.
The `$utilities` map contains all utilities and is later merged with your custom `$utilities` map if present. The utility map contains a keyed list of utility groups which accept the following options: The `$utilities` map contains all our utilities and is later merged with your custom `$utilities` map, if present. The utility map contains a keyed list of utility groups which accept the following options:
- `property`: Name of the property, this can be a string or an array of strings (needed for eg. horizontal paddings or margins). {{< bs-table "table text-left" >}}
- `responsive` _(optional)_: Boolean indicating if responsive classes need to be generated. `false` by default. | Option | Type | Description |
- `rfs` _(optional)_: Variable to enable fluid rescaling. Have a look at the [RFS]({{< docsref "/getting-started/rfs" >}}) page to find out how this works. `false` by default. | --- | --- | --- |
- `class` _(optional)_: Variable to change the class name if you don't want it to be the same as the property. In case you don't provide the `class` key and `property` key is an array of strings, the class name will be the first element of the `property` array. | `property` | **Required** | Name of the property, this can be a string or an array of strings (e.g., horizontal paddings or margins). |
- `values`: This can be a list of values or a map if you don't want the class name to be the same as the value. If null is used as map key, it isn't rendered. | `values` | **Required** | List of values, or a map if you don't want the class name to be the same as the value. If `null` is used as map key, it isn't compiled. |
- `print` _(optional)_: Boolean indicating if print classes need to be generated. `false` by default. | `class` | Optional | Variable for the class name if you don't want it to be the same as the property. In case you don't provide the `class` key and `property` key is an array of strings, the class name will be the first element of the `property` array. |
| `responsive` | Optional | Boolean indicating if responsive classes need to be generated. `false` by default. |
| `rfs` | Optional | Boolean to enable fluid rescaling. Have a look at the [RFS]({{< docsref "/getting-started/rfs" >}}) page to find out how this works. `false` by default. |
| `print` | Optional | Boolean indicating if print classes need to be generated. `false` by default. |
{{< /bs-table >}}
## API explained
## Adding utilities to the utility API All utility variables are added to the `$utilities` variable within our `_utilities.scss` stylesheet. Each group of utilities looks something like this:
All utility variables are added to the `$utilities` variable. Custom utility groups can added like this:
```scss ```scss
$utilities: ( $utilities: (
@ -38,30 +41,19 @@ $utilities: (
); );
``` ```
Output: Which outputs the following:
```css ```css
.opacity-0 { .opacity-0 { opacity: 0; }
opacity: 0; .opacity-25 { opacity: .25; }
} .opacity-50 { opacity: .5; }
.opacity-25 { .opacity-75 { opacity: .75; }
opacity: .25; .opacity-100 { opacity: 1; }
}
.opacity-50 {
opacity: .5;
}
.opacity-75 {
opacity: .75;
}
.opacity-100 {
opacity: 1;
}
``` ```
### Custom class prefix
## Changing the class prefix Use the `class` option to change the class prefix used in the compiled CSS:
With the `class` option, the class prefix can be changed:
```scss ```scss
$utilities: ( $utilities: (
@ -82,26 +74,16 @@ $utilities: (
Output: Output:
```css ```css
.o-0 { .o-0 { opacity: 0; }
opacity: 0; .o-25 { opacity: .25; }
} .o-50 { opacity: .5; }
.o-25 { .o-75 { opacity: .75; }
opacity: .25; .o-100 { opacity: 1; }
}
.o-50 {
opacity: .5;
}
.o-75 {
opacity: .75;
}
.o-100 {
opacity: 1;
}
``` ```
## Responsive utilities ### Responsive utilities
With the `responsive` option, responsive utility classes can be generated: Add the `responsive` boolean to generate responsive utilities (e.g., `.opacity-md-25`) across [all breakpoints]({{< docsref "/layout/breakpoints" >}}).
```scss ```scss
$utilities: ( $utilities: (
@ -122,95 +104,56 @@ $utilities: (
Output: Output:
```css ```css
.opacity-0 { .opacity-0 { opacity: 0; }
opacity: 0; .opacity-25 { opacity: .25; }
} .opacity-50 { opacity: .5; }
.opacity-25 { .opacity-75 { opacity: .75; }
opacity: .25; .opacity-100 { opacity: 1; }
}
.opacity-50 {
opacity: .5;
}
.opacity-75 {
opacity: .75;
}
.opacity-100 {
opacity: 1;
}
@media (min-width: 576px) { @media (min-width: 576px) {
.opacity-sm-0 { .opacity-sm-0 { opacity: 0; }
opacity: 0; .opacity-sm-25 { opacity: .25; }
} .opacity-sm-50 { opacity: .5; }
.opacity-sm-25 { .opacity-sm-75 { opacity: .75; }
opacity: .25; .opacity-sm-100 { opacity: 1; }
}
.opacity-sm-50 {
opacity: .5;
}
.opacity-sm-75 {
opacity: .75;
}
.opacity-sm-100 {
opacity: 1;
}
} }
@media (min-width: 768px) { @media (min-width: 768px) {
.opacity-md-0 { .opacity-md-0 { opacity: 0; }
opacity: 0; .opacity-md-25 { opacity: .25; }
} .opacity-md-50 { opacity: .5; }
.opacity-md-25 { .opacity-md-75 { opacity: .75; }
opacity: .25; .opacity-md-100 { opacity: 1; }
}
.opacity-md-50 {
opacity: .5;
}
.opacity-md-75 {
opacity: .75;
}
.opacity-md-100 {
opacity: 1;
}
} }
@media (min-width: 992px) { @media (min-width: 992px) {
.opacity-lg-0 { .opacity-lg-0 { opacity: 0; }
opacity: 0; .opacity-lg-25 { opacity: .25; }
} .opacity-lg-50 { opacity: .5; }
.opacity-lg-25 { .opacity-lg-75 { opacity: .75; }
opacity: .25; .opacity-lg-100 { opacity: 1; }
}
.opacity-lg-50 {
opacity: .5;
}
.opacity-lg-75 {
opacity: .75;
}
.opacity-lg-100 {
opacity: 1;
}
} }
@media (min-width: 1200px) { @media (min-width: 1200px) {
.opacity-xl-0 { .opacity-xl-0 { opacity: 0; }
opacity: 0; .opacity-xl-25 { opacity: .25; }
} .opacity-xl-50 { opacity: .5; }
.opacity-xl-25 { .opacity-xl-75 { opacity: .75; }
opacity: .25; .opacity-xl-100 { opacity: 1; }
}
.opacity-xl-50 {
opacity: .5;
}
.opacity-xl-75 {
opacity: .75;
}
.opacity-xl-100 {
opacity: 1;
} }
@media (min-width: 1400px) {
.opacity-xxl-0 { opacity: 0; }
.opacity-xxl-25 { opacity: .25; }
.opacity-xxl-50 { opacity: .5; }
.opacity-xxl-75 { opacity: .75; }
.opacity-xxl-100 { opacity: 1; }
} }
``` ```
## Changing utilities ### Changing utilities
Overriding excising utilities is possible by using the same key. For example if you want more responsive overflow Override existing utilities by using the same key. For example, if you want additional responsive overflow utility classes, you can do this:
utility classes you can do this:
```scss ```scss
$utilities: ( $utilities: (
@ -222,16 +165,14 @@ $utilities: (
); );
``` ```
### Print utilities
## Print utilities Enabling the `print` option will **also** generate utility classes for print, which are only applied within the `@media print { ... }` media query.
Enabling the `print` option will **also** generate utility classes for print.
```scss ```scss
$utilities: ( $utilities: (
"opacity": ( "opacity": (
property: opacity, property: opacity,
class: o,
print: true, print: true,
values: ( values: (
0: 0, 0: 0,
@ -247,42 +188,22 @@ $utilities: (
Output: Output:
```css ```css
.o-0 { .opacity-0 { opacity: 0; }
opacity: 0; .opacity-25 { opacity: .25; }
} .opacity-50 { opacity: .5; }
.o-25 { .opacity-75 { opacity: .75; }
opacity: .25; .opacity-100 { opacity: 1; }
}
.o-50 {
opacity: .5;
}
.o-75 {
opacity: .75;
}
.o-100 {
opacity: 1;
}
@media print { @media print {
.o-print-0 { .opacity-print-0 { opacity: 0; }
opacity: 0; .opacity-print-25 { opacity: .25; }
} .opacity-print-50 { opacity: .5; }
.o-print-25 { .opacity-print-75 { opacity: .75; }
opacity: .25; .opacity-print-100 { opacity: 1; }
}
.o-print-50 {
opacity: .5;
}
.o-print-75 {
opacity: .75;
}
.o-print-100 {
opacity: 1;
}
} }
``` ```
## Removing utilities ### Remove utilities
Utilities can also be removed by changing the group key to `null`: Utilities can also be removed by changing the group key to `null`: