Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update utilities API docs #32049

Merged
merged 4 commits into from Nov 5, 2020
Merged

Update utilities API docs #32049

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2355920
Editing and formatting utilities API page
mdo Nov 2, 2020
4737f79
docs: add info on modifying and adding utilities
Luke-zhang-04 Jul 19, 2020
6b9fe69
Big copy edits and testing
mdo Nov 3, 2020
96f617a
Merge branch 'main' into utils-api-edits
XhmikosR Nov 5, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
299 changes: 136 additions & 163 deletions site/content/docs/5.0/utilities/api.md
View file
Open in desktop
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,47 +188,79 @@ $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
## Using the API

Now that you're familiar with how the utilities API works, learn how to add your own custom classes and modify our default utilities.

### Add utilities

Utilities can also be removed by changing the group key to `null`:
New utilities can be added to the default `$utilities` map with a `map-merge`. Make sure our `_utilities.scss` is imported first, then use the `map-merge` to add your additional utilities. For example, here's how to add a responsive `cursor` utility with three values.

```scss
$utilities: (
"float": null,
@import "bootstrap/scss/utilities";

$utilities: map-merge(
$utilities,
(
"cursor": (
property: cursor,
class: cursor
responsive: true,
values: auto pointer grab,
)
)
);
```

### Modify utilities

Modify existing utilities in the default `$utilities` map with `map-get` and `map-merge` functions. In the example below, we're adding an additional value to the `width` utilities. Start with an initial `map-merge` and then specify which utility you want to modify. From there, fetch the nested `"width"` map with `map-get` to access and modify the utility's options and values.

```scss
@import "bootstrap/scss/utilities";

$utilities: map-merge(
$utilities,
(
"width": map-merge(
map-get($utilities, "width"),
(
values: map-merge(
map-get(map-get($utilities, "width"), "values"),
(10: 10%),
),
),
),
)
);
```

### Remove utilities

Remove any of the default utilities by setting the group key to `null`. For example, to remove all our `width` utilities, create a `$utilities` `map-merge` and add `"width": null` within.

```scss
@import "bootstrap/scss/utilities";

$utilities: map-merge(
$utilities,
(
"width": null
)
);
```