Skip to content

Commit

Permalink
Editing and formatting utilities API page
Browse files Browse the repository at this point in the history
  • Loading branch information
@mdo @XhmikosR
mdo authored and XhmikosR committed Nov 5, 2020
1 parent 366b841 commit 3b98597
Showing 1 changed file with 81 additions and 160 deletions.
241 changes: 81 additions & 160 deletions site/content/docs/5.0/utilities/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,21 +7,24 @@ aliases: "/docs/5.0/utilities/"
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).
- `responsive` _(optional)_: Boolean indicating if responsive classes need to be generated. `false` by default.
- `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.
- `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.
- `print` _(optional)_: Boolean indicating if print classes need to be generated. `false` by default.
{{< bs-table "table text-left" >}}
| Option | Type | Description |
| --- | --- | --- |
| `property` | **Required** | Name of the property, this can be a string or an array of strings (e.g., horizontal paddings or margins). |
| `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. |
| `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. Custom utility groups can added like this:
All utility variables are added to the `$utilities` variable within our `_utilities.scss` stylesheet. Each group of utilities looks something like this:

```scss
$utilities: (
Expand All @@ -38,30 +41,19 @@ $utilities: (
);
```

Output:
Which outputs the following:

```css
.opacity-0 {
opacity: 0;
}
.opacity-25 {
opacity: .25;
}
.opacity-50 {
opacity: .5;
}
.opacity-75 {
opacity: .75;
}
.opacity-100 {
opacity: 1;
}
.opacity-0 { opacity: 0; }
.opacity-25 { opacity: .25; }
.opacity-50 { opacity: .5; }
.opacity-75 { opacity: .75; }
.opacity-100 { opacity: 1; }
```

### Custom class prefix

## Changing the class prefix

With the `class` option, the class prefix can be changed:
Use the `class` option to change the class prefix used in the compiled CSS:

```scss
$utilities: (
Expand All @@ -82,26 +74,16 @@ $utilities: (
Output:

```css
.o-0 {
opacity: 0;
}
.o-25 {
opacity: .25;
}
.o-50 {
opacity: .5;
}
.o-75 {
opacity: .75;
}
.o-100 {
opacity: 1;
}
.o-0 { opacity: 0; }
.o-25 { opacity: .25; }
.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
$utilities: (
Expand All @@ -122,95 +104,56 @@ $utilities: (
Output:

```css
.opacity-0 {
opacity: 0;
}
.opacity-25 {
opacity: .25;
}
.opacity-50 {
opacity: .5;
}
.opacity-75 {
opacity: .75;
}
.opacity-100 {
opacity: 1;
}
.opacity-0 { opacity: 0; }
.opacity-25 { opacity: .25; }
.opacity-50 { opacity: .5; }
.opacity-75 { opacity: .75; }
.opacity-100 { opacity: 1; }

@media (min-width: 576px) {
.opacity-sm-0 {
opacity: 0;
}
.opacity-sm-25 {
opacity: .25;
}
.opacity-sm-50 {
opacity: .5;
}
.opacity-sm-75 {
opacity: .75;
}
.opacity-sm-100 {
opacity: 1;
}
.opacity-sm-0 { opacity: 0; }
.opacity-sm-25 { opacity: .25; }
.opacity-sm-50 { opacity: .5; }
.opacity-sm-75 { opacity: .75; }
.opacity-sm-100 { opacity: 1; }
}

@media (min-width: 768px) {
.opacity-md-0 {
opacity: 0;
}
.opacity-md-25 {
opacity: .25;
}
.opacity-md-50 {
opacity: .5;
}
.opacity-md-75 {
opacity: .75;
}
.opacity-md-100 {
opacity: 1;
}
.opacity-md-0 { opacity: 0; }
.opacity-md-25 { opacity: .25; }
.opacity-md-50 { opacity: .5; }
.opacity-md-75 { opacity: .75; }
.opacity-md-100 { opacity: 1; }
}

@media (min-width: 992px) {
.opacity-lg-0 {
opacity: 0;
}
.opacity-lg-25 {
opacity: .25;
}
.opacity-lg-50 {
opacity: .5;
}
.opacity-lg-75 {
opacity: .75;
}
.opacity-lg-100 {
opacity: 1;
}
.opacity-lg-0 { opacity: 0; }
.opacity-lg-25 { opacity: .25; }
.opacity-lg-50 { opacity: .5; }
.opacity-lg-75 { opacity: .75; }
.opacity-lg-100 { opacity: 1; }
}

@media (min-width: 1200px) {
.opacity-xl-0 {
opacity: 0;
}
.opacity-xl-25 {
opacity: .25;
}
.opacity-xl-50 {
opacity: .5;
}
.opacity-xl-75 {
opacity: .75;
}
.opacity-xl-100 {
opacity: 1;
}
.opacity-xl-0 { opacity: 0; }
.opacity-xl-25 { opacity: .25; }
.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
utility classes you can do this:
Override existing utilities by using the same key. For example, if you want additional responsive overflow utility classes, you can do this:

```scss
$utilities: (
Expand All @@ -222,16 +165,14 @@ $utilities: (
);
```

### Print utilities

## Print utilities

Enabling the `print` option will **also** generate utility classes for print.
Enabling the `print` option will **also** generate utility classes for print, which are only applied within the `@media print { ... }` media query.

```scss
$utilities: (
"opacity": (
property: opacity,
class: o,
print: true,
values: (
0: 0,
Expand All @@ -247,42 +188,22 @@ $utilities: (
Output:

```css
.o-0 {
opacity: 0;
}
.o-25 {
opacity: .25;
}
.o-50 {
opacity: .5;
}
.o-75 {
opacity: .75;
}
.o-100 {
opacity: 1;
}
.opacity-0 { opacity: 0; }
.opacity-25 { opacity: .25; }
.opacity-50 { opacity: .5; }
.opacity-75 { opacity: .75; }
.opacity-100 { opacity: 1; }

@media print {
.o-print-0 {
opacity: 0;
}
.o-print-25 {
opacity: .25;
}
.o-print-50 {
opacity: .5;
}
.o-print-75 {
opacity: .75;
}
.o-print-100 {
opacity: 1;
}
.opacity-print-0 { opacity: 0; }
.opacity-print-25 { opacity: .25; }
.opacity-print-50 { opacity: .5; }
.opacity-print-75 { opacity: .75; }
.opacity-print-100 { opacity: 1; }
}
```

## Removing utilities
### Remove utilities

Utilities can also be removed by changing the group key to `null`:

Expand Down

0 comments on commit 3b98597

Please sign in to comment.