diff --git a/scss/_maps.scss b/scss/_maps.scss index c8b9fa7e53..2770a67615 100644 --- a/scss/_maps.scss +++ b/scss/_maps.scss @@ -39,6 +39,16 @@ $utilities-bg: map-merge( $utilities-bg-colors: map-loop($utilities-bg, rgba-css-var, "$key", "bg") !default; // scss-docs-end utilities-bg-colors +// scss-docs-start utilities-border-colors +$utilities-border: map-merge( + $utilities-colors, + ( + "white": to-rgb($white) + ) +) !default; +$utilities-border-colors: map-loop($utilities-border, rgba-css-var, "$key", "border") !default; +// scss-docs-end utilities-border-colors + $negative-spacers: if($enable-negative-margins, negativify-map($spacers), null) !default; $gutters: $spacers !default; diff --git a/scss/_root.scss b/scss/_root.scss index 2927c343ff..ab0584e68a 100644 --- a/scss/_root.scss +++ b/scss/_root.scss @@ -50,5 +50,12 @@ } --#{$variable-prefix}body-bg: #{$body-bg}; // scss-docs-end root-body-variables + + // scss-docs-start root-border-var + --#{$variable-prefix}border-width: #{$border-width}; + --#{$variable-prefix}border-style: solid; + --#{$variable-prefix}border-color: #{$border-color}; + --#{$variable-prefix}border-radius: #{$border-radius}; + // scss-docs-end root-border-var // stylelint-enable custom-property-empty-line-before } diff --git a/scss/_utilities.scss b/scss/_utilities.scss index 4d65bb88b5..7fc732acf6 100644 --- a/scss/_utilities.scss +++ b/scss/_utilities.scss @@ -98,15 +98,29 @@ $utilities: map-merge( // scss-docs-start utils-borders "border": ( property: border, + local-vars: ( + "border-opacity": 1 + ), values: ( - null: $border-width solid $border-color, + null: var(--#{$variable-prefix}border-width) var(--#{$variable-prefix}border-style) var(--#{$variable-prefix}border-color), 0: 0, ) ), + "border-opacity": ( + css-var: true, + class: border-opacity, + values: ( + 10: .1, + 25: .25, + 50: .5, + 75: .75, + 100: 1 + ) + ), "border-top": ( property: border-top, values: ( - null: $border-width solid $border-color, + null: var(--#{$variable-prefix}border-width) var(--#{$variable-prefix}border-style) var(--#{$variable-prefix}border-color), 0: 0, ) ), @@ -114,14 +128,14 @@ $utilities: map-merge( property: border-right, class: border-end, values: ( - null: $border-width solid $border-color, + null: var(--#{$variable-prefix}border-width) var(--#{$variable-prefix}border-style) var(--#{$variable-prefix}border-color), 0: 0, ) ), "border-bottom": ( property: border-bottom, values: ( - null: $border-width solid $border-color, + null: var(--#{$variable-prefix}border-width) var(--#{$variable-prefix}border-style) var(--#{$variable-prefix}border-color), 0: 0, ) ), @@ -129,17 +143,18 @@ $utilities: map-merge( property: border-left, class: border-start, values: ( - null: $border-width solid $border-color, + null: var(--#{$variable-prefix}border-width) var(--#{$variable-prefix}border-style) var(--#{$variable-prefix}border-color), 0: 0, ) ), "border-color": ( - property: border-color, + css-var: true, + css-variable-name: border-color, class: border, - values: map-merge($theme-colors, ("white": $white)) + values: $utilities-border-colors ), "border-width": ( - property: border-width, + css-var: true, class: border, values: $border-widths ), diff --git a/scss/mixins/_utilities.scss b/scss/mixins/_utilities.scss index e871b42336..b2c6683d7d 100644 --- a/scss/mixins/_utilities.scss +++ b/scss/mixins/_utilities.scss @@ -20,6 +20,9 @@ $property-class: if(map-has-key($utility, class), map-get($utility, class), nth($properties, 1)); $property-class: if($property-class == null, "", $property-class); + // Use custom CSS variable name if present, otherwise default to `class` + $css-variable-name: if(map-has-key($utility, css-variable-name), map-get($utility, css-variable-name), map-get($utility, class)); + // State params to generate pseudo-classes $state: if(map-has-key($utility, state), map-get($utility, state), ()); @@ -52,20 +55,20 @@ @if $is-css-var { .#{$property-class + $infix + $property-class-modifier} { - --#{$variable-prefix}#{$property-class}: #{$value}; + --#{$variable-prefix}#{$css-variable-name}: #{$value}; } @each $pseudo in $state { .#{$property-class + $infix + $property-class-modifier}-#{$pseudo}:#{$pseudo} { - --#{$variable-prefix}#{$property-class}: #{$value}; + --#{$variable-prefix}#{$css-variable-name}: #{$value}; } } } @else { .#{$property-class + $infix + $property-class-modifier} { @each $property in $properties { @if $is-local-vars { - @each $local-var, $value in $is-local-vars { - --#{$variable-prefix}#{$local-var}: #{$value}; + @each $local-var, $variable in $is-local-vars { + --#{$variable-prefix}#{$local-var}: #{$variable}; } } #{$property}: $value if($enable-important-utilities, !important, null); diff --git a/site/content/docs/5.1/utilities/api.md b/site/content/docs/5.1/utilities/api.md index f961a5da9b..16270ad511 100644 --- a/site/content/docs/5.1/utilities/api.md +++ b/site/content/docs/5.1/utilities/api.md @@ -18,6 +18,7 @@ The `$utilities` map contains all our utilities and is later merged with your cu | [`values`](#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, `class` is not prepended to the class name. | | [`class`](#class) | Optional | null | Name of the generated class. If not provided and `property` is an array of strings, `class` will default to the first element of the `property` array. If not provided and `property` is a string, the `values` keys are used for the `class` names. | | [`css-var`](#css-variable-utilities) | Optional | `false` | Boolean to generate CSS variables instead of CSS rules. | +| [`css-variable-name`](#css-variable-utilities) | Optional | null | Custom un-prefixed name for the CSS variable inside the ruleset. | | [`local-vars`](#local-css-variables) | Optional | null | Map of local CSS variables to generate in addition to the CSS rules. | | [`state`](#states) | Optional | null | List of pseudo-class variants (e.g., `:hover` or `:focus`) to generate. | | [`responsive`](#responsive) | Optional | `false` | Boolean indicating if responsive classes should be generated. | @@ -158,12 +159,15 @@ Output: ### CSS variable utilities -Set the `css-var` boolean option to `true` and the API will generate local CSS variables for the given selector instead of the usual `property: value` rules. Consider our `.text-opacity-*` utilities: +Set the `css-var` boolean option to `true` and the API will generate local CSS variables for the given selector instead of the usual `property: value` rules. Add an optional `css-variable-name` to set a different CSS variable name than the class name. + +Consider our `.text-opacity-*` utilities. If we add the `css-variable-name` option, we'll get a custom output. ```scss $utilities: ( "text-opacity": ( css-var: true, + css-variable-name: text-alpha, class: text-opacity, values: ( 25: .25, @@ -178,10 +182,10 @@ $utilities: ( Output: ```css -.text-opacity-25 { --bs-text-opacity: .25; } -.text-opacity-50 { --bs-text-opacity: .5; } -.text-opacity-75 { --bs-text-opacity: .75; } -.text-opacity-100 { --bs-text-opacity: 1; } +.text-opacity-25 { --bs-text-alpha: .25; } +.text-opacity-50 { --bs-text-alpha: .5; } +.text-opacity-75 { --bs-text-alpha: .75; } +.text-opacity-100 { --bs-text-alpha: 1; } ``` ### Local CSS variables diff --git a/site/content/docs/5.1/utilities/borders.md b/site/content/docs/5.1/utilities/borders.md index 6ba1174c9d..e76c461a3a 100644 --- a/site/content/docs/5.1/utilities/borders.md +++ b/site/content/docs/5.1/utilities/borders.md @@ -30,7 +30,7 @@ Use border utilities to add or remove an element's borders. Choose from all bord {{< /example >}} -## Border color +## Color Change the border color using utilities built on our theme colors. @@ -43,7 +43,45 @@ Change the border color using utilities built on our theme colors. {{< /example >}} -## Border-width +## Opacity + +Added in v5.2.0 + +Bootstrap `border-{color}` utilities are generated with Sass using CSS variables. This allows for real-time color changes without compilation and dynamic alpha transparency changes. + +### How it works + +Consider our default `.border-success` utility. + +```css +.border-success { + --bs-border-opacity: 1; + border-color: rgba(var(--bs-success-rgb), var(--bs-border-opacity)) !important; +} +``` + +We use an RGB version of our `--bs-success` (with the value of `25, 135, 84`) CSS variable and attached a second CSS variable, `--bs-border-opacity`, for the alpha transparency (with a default value `1` thanks to a local CSS variable). That means anytime you use `.border-success` now, your computed `color` value is `rgba(25, 135, 84, 1)`. The local CSS variable inside each `.border-*` class avoids inheritance issues so nested instances of the utilities don't automatically have a modified alpha transparency. + +### Example + +To change that opacity, override `--bs-border-opacity` via custom styles or inline styles. + +{{< example >}} +