Utility API·续

Need multiple pseudo-classes? Use a space-separated list of states: state: hover focus.

$utilities: (
  "opacity": (
    property: opacity,
    class: opacity,
    state: hover,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

Output:

.hover\:opacity-0:hover { opacity: 0; }
.hover\:opacity-25:hover { opacity: .25; }
.hover\:opacity-50:hover { opacity: .5; }
.hover\:opacity-75:hover { opacity: .75; }
.hover\:opacity-100:hover { opacity: 1; }

Responsive

Add the responsive boolean to generate responsive utilities (e.g., .md\:opacity-25) across all breakpoints.

$utilities: (
  "opacity": (
    property: opacity,
    responsive: true,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

Output:

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

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

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

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

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

@media (min-width: 1536px) {
  .\32 xl\:opacity-0 { opacity: 0; }
  .\32 xl\:opacity-25 { opacity: .25; }
  .\32 xl\:opacity-50 { opacity: .5; }
  .\32 xl\:opacity-75 { opacity: .75; }
  .\32 xl\:opacity-100 { opacity: 1; }
}

Print

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

$utilities: (
  "opacity": (
    property: opacity,
    print: true,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

Output:

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

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

Dark

Enabling the dark option generates dark: prefixed classes scoped to @media (prefers-color-scheme: dark). This follows the same prefix convention as responsive and print utilities.

$utilities: (
  "bg-color": (
    property: background-color,
    class: bg,
    dark: true,
    values: (
      white: #fff,
      black: #000,
    )
  )
);

Output:

.bg-white { background-color: #fff; }
.bg-black { background-color: #000; }

@media (prefers-color-scheme: dark) {
  .dark\:bg-white { background-color: #fff; }
  .dark\:bg-black { background-color: #000; }
}

Enabled

Set enabled: false to suppress output for a utility without removing it from the $utilities map. This is useful when you want to keep the utility's definition available for reference or downstream map.get() calls, but don't want it to emit any CSS. See Using the API for the load order this example needs.

// _my-utilities.scss
@use "sass:map";
@use "bootstrap/scss/config" as *;
@use "bootstrap/scss/utilities";

$utilities: map.merge(
  $utilities,
  (
    "float": map.merge(
      map.get($utilities, "float"),
      (enabled: false),
    ),
  )
);

Importance

Utilities generated by the API no longer include !important by default in v6. This is because we now use CSS layers to ensure utilities override components and modifier classes as intended. You can enable !important on a per-utility basis by setting the important option to true.

$utilities: (
  "opacity": (
    property: opacity,
    important: true,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

This will generate utilities with !important:

.opacity-0 { opacity: 0 !important; }
.opacity-25 { opacity: .25 !important; }
.opacity-50 { opacity: .5 !important; }
.opacity-75 { opacity: .75 !important; }
.opacity-100 { opacity: 1 !important; }

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.

The examples below use two patterns. Pick the pattern that matches your change.

  • One file—Configure $utilities when you load bootstrap/scss/bootstrap. Use this pattern to add a utility, to replace a utility, or to remove a utility.
  • Two files—Put a map.merge() call in a partial. Then load the partial before bootstrap/scss/bootstrap. Use this pattern when your change must read the default definition. Examples are a new value, a new class prefix, or new responsive variants on a group you keep.

The one-file pattern needs one @use rule:

// my-bootstrap.scss
@use "bootstrap/scss/bootstrap" with (
  $utilities: (
    // Your utility groups go here
  )
);

Bootstrap merges your map with map.merge(). This merge is shallow. Your utility group replaces the whole default group with the same key. Supply the property and values keys in every group that emits CSS.

Sass cannot read a module and configure the same module in one file. Some changes therefore need the two-file pattern. The bootstrap/scss/config module declares $utilities. The bootstrap/scss/utilities module fills it with the default definitions. Your partial loads both modules. Then it writes the new map back to the config module.

The partial loads the config module with as *. This avoids a namespace prefix, so you can reference $utilities directly. An assignment to $utilities then writes back to the config module.

For a utility-only build, load bootstrap/scss/utilities and then bootstrap/scss/utilities/api. The API module emits the utility classes and nothing else.

// my-bootstrap-utilities.scss
@use "bootstrap/scss/utilities" with (
  $utilities: (
    // Your utility groups go here
  )
);
@use "bootstrap/scss/utilities/api";

Override utilities

Override an existing utility with the same key. Pass the new definition in the $utilities configuration when you load Bootstrap. For example, take our existing overflow utility class definition:

If you want to make those responsive, and adjust the values used, you can do this:

// my-bootstrap.scss
@use "bootstrap/scss/bootstrap" with (
  $utilities: (
    "overflow": (
      property: overflow,
      responsive: true,
      values: visible hidden scroll auto,
    ),
  )
);

Your group replaces the default group. Keep the property key, or the build stops with an error.

Add utilities

Add a new utility with the $utilities configuration. Bootstrap merges your map on top of its defaults, so supply only the new utilities.

// my-bootstrap.scss
@use "bootstrap/scss/bootstrap" with (
  $utilities: (
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    ),
  )
);

Modify utilities

Modify an existing utility with map.get() and map.merge(). This change reads the default definition, so it needs the two-file pattern. In the example below, we’re adding an additional value to the width utilities:

// _my-utilities.scss
@use "sass:map";
@use "bootstrap/scss/config" as *;
// Fills `$utilities` with the default definitions
@use "bootstrap/scss/utilities";

$utilities: map.merge(
  $utilities,
  (
    "width": map.merge(
      map.get($utilities, "width"),
      (
        values: map.merge(
          map.get(map.get($utilities, "width"), "values"),
          (20: 20%),
        ),
      ),
    ),
  )
);

Load your partial first. Then load Bootstrap:

// my-bootstrap.scss
@use "my-utilities";
@use "bootstrap/scss/bootstrap";

Enable responsive

You can enable responsive classes for an existing set of utilities that are not currently responsive by default. This change keeps the default definition, so it needs the two-file pattern. For example, to make the border classes responsive:

// _my-utilities.scss
@use "sass:map";
@use "bootstrap/scss/config" as *;
@use "bootstrap/scss/utilities";

$utilities: map.merge(
  $utilities,
  (
    "border": map.merge(
      map.get($utilities, "border"),
      (responsive: true),
    ),
  )
);

Load this partial before bootstrap/scss/bootstrap, as shown above. You can also restate the whole group with the one-file pattern. See Override utilities.

This will now generate responsive variations of .border and .border-0 for each breakpoint. Your generated CSS will look like this:

.border { ... }
.border-0 { ... }

@media (min-width: 576px) {
  .sm\:border { ... }
  .sm\:border-0 { ... }
}

@media (min-width: 768px) {
  .md\:border { ... }
  .md\:border-0 { ... }
}

@media (min-width: 1024px) {
  .lg\:border { ... }
  .lg\:border-0 { ... }
}

@media (min-width: 1280px) {
  .xl\:border { ... }
  .xl\:border-0 { ... }
}

@media (min-width: 1536px) {
  .2xl\:border { ... }
  .2xl\:border-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. This change keeps the default definition, so it needs the two-file pattern. For example, to rename .ms-* utilities to oldish .ml-*:

// _my-utilities.scss
@use "sass:map";
@use "bootstrap/scss/config" as *;
@use "bootstrap/scss/utilities";

$utilities: map.merge(
  $utilities,
  (
    "margin-start": map.merge(
      map.get($utilities, "margin-start"),
      (class: ml),
    ),
  )
);

Load this partial before bootstrap/scss/bootstrap, as shown above.

Remove utilities

Remove a default utility with the $utilities configuration. Set the group key to null.

// my-bootstrap.scss
@use "bootstrap/scss/bootstrap" with (
  $utilities: (
    "width": null,
    "float": null,
  )
);

You can also remove utilities with the map.remove() Sass function. This function reads the default map, so it needs the two-file pattern.

// _my-utilities.scss
@use "sass:map";
@use "bootstrap/scss/config" as *;
@use "bootstrap/scss/utilities";

$utilities: map.remove($utilities, "width", "float");

Load this partial before bootstrap/scss/bootstrap, as shown above.

Add, remove, modify

You can add, remove, and modify many utilities all at once with the map.merge() Sass function. Here’s how you can combine the previous examples into one larger map.

// _my-utilities.scss
@use "sass:map";
@use "bootstrap/scss/config" as *;
@use "bootstrap/scss/utilities";

$utilities: map.merge(
  $utilities,
  (
    // Remove the `width` utility
    "width": null,
    // Make an existing utility responsive
    "border": map.merge(
      map.get($utilities, "border"),
      (responsive: true),
    ),
    // Add a new utility
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    ),
  )
);

Then load the partial before Bootstrap:

// my-bootstrap.scss
@use "my-utilities";
@use "bootstrap/scss/bootstrap";