Convey meaning through `background-color` and add decoration with gradients.
| Class | Styles |
|---|---|
| .bg-primary | --cui-bg: var(--cui-primary-bg); background-color: var(--cui-bg); |
| .bg-secondary | --cui-bg: var(--cui-secondary-bg); background-color: var(--cui-bg); |
| .bg-success | --cui-bg: var(--cui-success-bg); background-color: var(--cui-bg); |
| .bg-info | --cui-bg: var(--cui-info-bg); background-color: var(--cui-bg); |
| .bg-warning | --cui-bg: var(--cui-warning-bg); background-color: var(--cui-bg); |
| .bg-danger | --cui-bg: var(--cui-danger-bg); background-color: var(--cui-bg); |
| .bg-inverse | --cui-bg: var(--cui-inverse-bg); background-color: var(--cui-bg); |
| .bg-black | --cui-bg: var(--cui-bg-black); background-color: var(--cui-bg); |
| .bg-white | --cui-bg: var(--cui-bg-white); background-color: var(--cui-bg); |
| .bg-body | --cui-bg: var(--cui-bg-body); background-color: var(--cui-bg); |
| .bg-1 | --cui-bg: var(--cui-bg-1); background-color: var(--cui-bg); |
| .bg-2 | --cui-bg: var(--cui-bg-2); background-color: var(--cui-bg); |
| .bg-3 | --cui-bg: var(--cui-bg-3); background-color: var(--cui-bg); |
| .bg-4 | --cui-bg: var(--cui-bg-4); background-color: var(--cui-bg); |
| .bg-fg | --cui-bg: var(--cui-bg-fg); background-color: var(--cui-bg); |
| .bg-transparent | --cui-bg: var(--cui-bg-transparent); background-color: var(--cui-bg); |
| .bg-body-secondary | --cui-bg: var(--cui-bg-3); background-color: var(--cui-bg); |
| .bg-body-tertiary | --cui-bg: var(--cui-bg-2); background-color: var(--cui-bg); |
| .bg-subtle-primary | --cui-bg: var(--cui-primary-bg-subtle); background-color: var(--cui-bg); |
| .bg-subtle-secondary | --cui-bg: var(--cui-secondary-bg-subtle); background-color: var(--cui-bg); |
| .bg-subtle-success | --cui-bg: var(--cui-success-bg-subtle); background-color: var(--cui-bg); |
| .bg-subtle-info | --cui-bg: var(--cui-info-bg-subtle); background-color: var(--cui-bg); |
| .bg-subtle-warning | --cui-bg: var(--cui-warning-bg-subtle); background-color: var(--cui-bg); |
| .bg-subtle-danger | --cui-bg: var(--cui-danger-bg-subtle); background-color: var(--cui-bg); |
| .bg-subtle-inverse | --cui-bg: var(--cui-inverse-bg-subtle); background-color: var(--cui-bg); |
| .bg-muted-primary | --cui-bg: var(--cui-primary-bg-muted); background-color: var(--cui-bg); |
| .bg-muted-secondary | --cui-bg: var(--cui-secondary-bg-muted); background-color: var(--cui-bg); |
| .bg-muted-success | --cui-bg: var(--cui-success-bg-muted); background-color: var(--cui-bg); |
| .bg-muted-info | --cui-bg: var(--cui-info-bg-muted); background-color: var(--cui-bg); |
| .bg-muted-warning | --cui-bg: var(--cui-warning-bg-muted); background-color: var(--cui-bg); |
| .bg-muted-danger | --cui-bg: var(--cui-danger-bg-muted); background-color: var(--cui-bg); |
| .bg-muted-inverse | --cui-bg: var(--cui-inverse-bg-muted); background-color: var(--cui-bg); |
| .bg-10 | background-color: color-mix(in oklch, var(--cui-bg) 10%, transparent); |
| .bg-20 | background-color: color-mix(in oklch, var(--cui-bg) 20%, transparent); |
| .bg-30 | background-color: color-mix(in oklch, var(--cui-bg) 30%, transparent); |
| .bg-40 | background-color: color-mix(in oklch, var(--cui-bg) 40%, transparent); |
| .bg-50 | background-color: color-mix(in oklch, var(--cui-bg) 50%, transparent); |
| .bg-60 | background-color: color-mix(in oklch, var(--cui-bg) 60%, transparent); |
| .bg-70 | background-color: color-mix(in oklch, var(--cui-bg) 70%, transparent); |
| .bg-80 | background-color: color-mix(in oklch, var(--cui-bg) 80%, transparent); |
| .bg-90 | background-color: color-mix(in oklch, var(--cui-bg) 90%, transparent); |
| .bg-100 | background-color: var(--cui-bg); |
| .bg-primary-subtle | --cui-bg: var(--cui-primary-bg-subtle); background-color: var(--cui-bg); |
| .bg-secondary-subtle | --cui-bg: var(--cui-secondary-bg-subtle); background-color: var(--cui-bg); |
| .bg-success-subtle | --cui-bg: var(--cui-success-bg-subtle); background-color: var(--cui-bg); |
| .bg-info-subtle | --cui-bg: var(--cui-info-bg-subtle); background-color: var(--cui-bg); |
| .bg-warning-subtle | --cui-bg: var(--cui-warning-bg-subtle); background-color: var(--cui-bg); |
| .bg-danger-subtle | --cui-bg: var(--cui-danger-bg-subtle); background-color: var(--cui-bg); |
| .bg-inverse-subtle | --cui-bg: var(--cui-inverse-bg-subtle); background-color: var(--cui-bg); |
| .bg-primary-muted | --cui-bg: var(--cui-primary-bg-muted); background-color: var(--cui-bg); |
| .bg-secondary-muted | --cui-bg: var(--cui-secondary-bg-muted); background-color: var(--cui-bg); |
| .bg-success-muted | --cui-bg: var(--cui-success-bg-muted); background-color: var(--cui-bg); |
| .bg-info-muted | --cui-bg: var(--cui-info-bg-muted); background-color: var(--cui-bg); |
| .bg-warning-muted | --cui-bg: var(--cui-warning-bg-muted); background-color: var(--cui-bg); |
| .bg-danger-muted | --cui-bg: var(--cui-danger-bg-muted); background-color: var(--cui-bg); |
| .bg-inverse-muted | --cui-bg: var(--cui-inverse-bg-muted); background-color: var(--cui-bg); |
| .bg-opacity-10 | background-color: color-mix(in oklch, var(--cui-bg) 10%, transparent); |
| .bg-opacity-15 | background-color: color-mix(in oklch, var(--cui-bg) 15%, transparent); |
| .bg-opacity-25 | background-color: color-mix(in oklch, var(--cui-bg) 25%, transparent); |
| .bg-opacity-50 | background-color: color-mix(in oklch, var(--cui-bg) 50%, transparent); |
| .bg-opacity-75 | background-color: color-mix(in oklch, var(--cui-bg) 75%, transparent); |
| .bg-opacity-100 | background-color: var(--cui-bg); |
| .bg-gradient | background-image: var(--cui-gradient); |
Background color
Similar to the contextual text color classes, set the background of an element to any contextual class. Background utilities do not set color, so in some cases you’ll want to use .fg-* color utilities.
Each theme color comes in three weights: the solid color, .bg-muted-* and .bg-subtle-*. The two lighter ones are surfaces to read text on, and .fg-emphasis-* is the color that reads on them — .bg-muted-* is the step you want when a subtle surface has to separate from a subtle surface behind it, which is what a hovered row or a selected item needs.
<div class="p-4 mb-3 text-bg-primary">.bg-primary</div>
<div class="p-4 mb-3 bg-muted-primary fg-emphasis-primary">.bg-muted-primary</div>
<div class="p-4 mb-3 bg-subtle-primary fg-emphasis-primary">.bg-subtle-primary</div>
<div class="p-4 mb-3 text-bg-secondary">.bg-secondary</div>
<div class="p-4 mb-3 bg-muted-secondary fg-emphasis-secondary">.bg-muted-secondary</div>
<div class="p-4 mb-3 bg-subtle-secondary fg-emphasis-secondary">.bg-subtle-secondary</div>
<div class="p-4 mb-3 text-bg-success">.bg-success</div>
<div class="p-4 mb-3 bg-muted-success fg-emphasis-success">.bg-muted-success</div>
<div class="p-4 mb-3 bg-subtle-success fg-emphasis-success">.bg-subtle-success</div>
<div class="p-4 mb-3 text-bg-info">.bg-info</div>
<div class="p-4 mb-3 bg-muted-info fg-emphasis-info">.bg-muted-info</div>
<div class="p-4 mb-3 bg-subtle-info fg-emphasis-info">.bg-subtle-info</div>
<div class="p-4 mb-3 text-bg-warning">.bg-warning</div>
<div class="p-4 mb-3 bg-muted-warning fg-emphasis-warning">.bg-muted-warning</div>
<div class="p-4 mb-3 bg-subtle-warning fg-emphasis-warning">.bg-subtle-warning</div>
<div class="p-4 mb-3 text-bg-danger">.bg-danger</div>
<div class="p-4 mb-3 bg-muted-danger fg-emphasis-danger">.bg-muted-danger</div>
<div class="p-4 mb-3 bg-subtle-danger fg-emphasis-danger">.bg-subtle-danger</div>
<div class="p-4 mb-3 text-bg-inverse">.bg-inverse</div>
<div class="p-4 mb-3 bg-muted-inverse fg-emphasis-inverse">.bg-muted-inverse</div>
<div class="p-4 mb-3 bg-subtle-inverse fg-emphasis-inverse">.bg-subtle-inverse</div>
<div class="p-4 mb-3 bg-body fg-body">.bg-body</div>
<div class="p-4 mb-3 bg-black fg-white">.bg-black</div>
<div class="p-4 mb-3 bg-white fg-black">.bg-white</div>
<div class="p-4 mb-3 bg-transparent fg-body">.bg-transparent</div>Surface ladder
Five neutral surfaces run from the page background to the deepest panel. The numbers say how far a surface sits from the body — .bg-1 is barely off the page, .bg-4 is the deepest — and the ladder keeps its order in both color schemes.
<div class="p-4 mb-3 bg-body">.bg-body</div>
<div class="p-4 mb-3 bg-1">.bg-1</div>
<div class="p-4 mb-3 bg-2">.bg-2</div>
<div class="p-4 mb-3 bg-3">.bg-3</div>
<div class="p-4 mb-3 bg-4">.bg-4</div>.bg-body-secondary and .bg-body-tertiary are deprecated names for .bg-3 and .bg-2 — they render identically and go away in v7. The ordinal names replace them because the old adjectives ran backwards for backgrounds: “tertiary” sat closer to the page than “secondary”.
Background gradient
By adding a .bg-gradient class, a linear gradient is added as background image to the backgrounds. This gradient starts with a semi-transparent white which fades out to the bottom.
Do you need a gradient in your custom CSS? Just add background-image: var(gradient);.
Opacity
Every .bg-* utility writes its colour into --cui-bg and reads it back, so a companion .bg-{percentage} class can mix that colour with transparent through color-mix(), in the browser, without recompiling Sass.
.bg-success {
--cui-bg: var(--cui-success-bg);
background-color: var(--cui-bg);
}
.bg-50 {
background-color: color-mix(in oklch, var(--cui-bg) 50%, transparent);
}Override --cui-bg to repaint the utility with another colour; the opacity class keeps working, because it reads whatever the token holds.
<div class="text-bg-success p-3">This is default success background</div>
<div class="bg-success p-3 bg-90">This is 90% opacity success background</div>
<div class="bg-success p-3 bg-70">This is 70% opacity success background</div>
<div class="bg-success p-3 bg-50">This is 50% opacity success background</div>
<div class="bg-success p-3 bg-30">This is 30% opacity success background</div>
<div class="bg-success p-3 bg-10">This is 10% opacity success background</div>.bg-opacity-{10|15|25|50|75|100} and .bg-{color}-subtle / .bg-{color}-muted are the deprecated v5 spellings of .bg-{percentage}, .bg-subtle-{color} and .bg-muted-{color}; they still render and are removed in v7.
Customizing
In addition to the following Sass functionality, consider reading about our included CSS custom properties (aka CSS variables) for colors and more.
Sass variables
Most background-color utilities are generated by our theme colors, reassigned from our generic color palette variables.
$primary: oklch(52.945% 0.19103 278.34) !default;
$success: oklch(55.1% 0.173 145) !default;
$info: oklch(57.4% 0.196 256) !default;
$warning: oklch(84% 0.172 85) !default;
$danger: oklch(58.7% 0.237 23.81) !default;
$gray: oklch(60% 0.03948 265.02) !default;Sass maps
The surface ladder is one map: each key is one .bg-{key} utility and the --cui-bg-{key} token behind it, in light and dark mode. Add a key to add a rung, override one to retune it:
$theme-bgs: () !default;
// stylelint-disable-next-line scss/dollar-variable-default
$theme-bgs: defaults(
(
"body": light-dark(var(--cui-white), var(--cui-gray-975)),
"1": light-dark(var(--cui-gray-025), var(--cui-gray-950)),
"2": light-dark(var(--cui-gray-050), var(--cui-gray-900)),
"3": light-dark(var(--cui-gray-100), var(--cui-gray-800)),
"4": light-dark(var(--cui-gray-200), var(--cui-gray-700)),
"fg": var(--cui-fg-body),
"white": var(--cui-white),
"black": var(--cui-black),
"transparent": transparent,
"inherit": inherit,
),
$theme-bgs
);.bg-{color}-subtle and .bg-{color}-muted read the bg-subtle and bg-muted slot of every entry through theme-color-refs(), in light and dark mode.
Theme colors are then put into a Sass map so we can loop over them to generate our utilities, component modifiers, and more.
$theme-colors: () !default;
// stylelint-disable-next-line scss/dollar-variable-default
$theme-colors: defaults(
(
"primary": (
"base": var(--cui-primary-500),
"fg": light-dark(var(--cui-primary-600), var(--cui-primary-400)),
"fg-emphasis": light-dark(var(--cui-primary-800), var(--cui-primary-200)),
"bg": var(--cui-primary-500),
"bg-subtle": light-dark(var(--cui-primary-100), var(--cui-primary-900)),
"bg-muted": light-dark(var(--cui-primary-200), var(--cui-primary-800)),
"border": light-dark(var(--cui-primary-300), var(--cui-primary-600)),
"focus-ring": color-mix(in oklch, var(--cui-primary-base) calc(var(--cui-focus-ring-opacity) * 100%), transparent),
"contrast": var(--cui-white),
),
"secondary": (
"base": var(--cui-gray-200),
"fg": light-dark(var(--cui-gray-600), var(--cui-gray-400)),
"fg-emphasis": light-dark(var(--cui-gray-800), var(--cui-gray-200)),
"bg": light-dark(var(--cui-gray-100), var(--cui-gray-600)),
"bg-subtle": light-dark(var(--cui-gray-025), var(--cui-gray-800)),
"bg-muted": light-dark(var(--cui-gray-050), var(--cui-gray-700)),
"border": light-dark(var(--cui-gray-300), var(--cui-gray-600)),
"focus-ring": color-mix(in oklch, light-dark(var(--cui-gray-500), var(--cui-gray-300)) calc(var(--cui-focus-ring-opacity) * 100%), transparent),
"contrast": light-dark(var(--cui-gray-900), var(--cui-white)),
),
"success": (
"base": var(--cui-success-500),
"fg": light-dark(var(--cui-success-600), var(--cui-success-400)),
"fg-emphasis": light-dark(var(--cui-success-800), var(--cui-success-200)),
"bg": var(--cui-success-500),
"bg-subtle": light-dark(var(--cui-success-100), var(--cui-success-900)),
"bg-muted": light-dark(var(--cui-success-200), var(--cui-success-800)),
"border": light-dark(var(--cui-success-300), var(--cui-success-600)),
"focus-ring": color-mix(in oklch, var(--cui-success-base) calc(var(--cui-focus-ring-opacity) * 100%), transparent),
"contrast": var(--cui-white),
),
"info": (
"base": var(--cui-info-500),
"fg": light-dark(var(--cui-info-700), var(--cui-info-300)),
"fg-emphasis": light-dark(var(--cui-info-800), var(--cui-info-200)),
"bg": var(--cui-info-500),
"bg-subtle": light-dark(var(--cui-info-100), var(--cui-info-900)),
"bg-muted": light-dark(var(--cui-info-200), var(--cui-info-800)),
"border": light-dark(var(--cui-info-300), var(--cui-info-600)),
"focus-ring": color-mix(in oklch, var(--cui-info-base) calc(var(--cui-focus-ring-opacity) * 100%), transparent),
"contrast": var(--cui-white),
),
"warning": (
"base": var(--cui-warning-500),
"fg": light-dark(var(--cui-warning-700), var(--cui-warning-300)),
"fg-emphasis": light-dark(var(--cui-warning-800), var(--cui-warning-200)),
"bg": var(--cui-warning-500),
"bg-subtle": light-dark(var(--cui-warning-100), var(--cui-warning-900)),
"bg-muted": light-dark(var(--cui-warning-200), var(--cui-warning-800)),
"border": light-dark(var(--cui-warning-300), var(--cui-warning-600)),
"focus-ring": color-mix(in oklch, var(--cui-warning-base) calc(var(--cui-focus-ring-opacity) * 100%), transparent),
"contrast": var(--cui-black),
),
"danger": (
"base": var(--cui-danger-500),
"fg": light-dark(var(--cui-danger-600), var(--cui-danger-400)),
"fg-emphasis": light-dark(var(--cui-danger-800), var(--cui-danger-200)),
"bg": var(--cui-danger-500),
"bg-subtle": light-dark(var(--cui-danger-100), var(--cui-danger-900)),
"bg-muted": light-dark(var(--cui-danger-200), var(--cui-danger-800)),
"border": light-dark(var(--cui-danger-300), var(--cui-danger-600)),
"focus-ring": color-mix(in oklch, var(--cui-danger-base) calc(var(--cui-focus-ring-opacity) * 100%), transparent),
"contrast": var(--cui-white),
),
"inverse": (
"base": var(--cui-gray-900),
"fg": light-dark(var(--cui-gray-900), var(--cui-gray-200)),
"fg-emphasis": light-dark(var(--cui-black), var(--cui-white)),
"bg": light-dark(var(--cui-gray-900), var(--cui-gray-100)),
"bg-subtle": light-dark(var(--cui-gray-100), var(--cui-gray-900)),
"bg-muted": light-dark(var(--cui-gray-200), var(--cui-gray-700)),
"border": light-dark(var(--cui-gray-400), var(--cui-gray-600)),
"focus-ring": color-mix(in oklch, light-dark(var(--cui-gray-900), var(--cui-gray-100)) calc(var(--cui-focus-ring-opacity) * 100%), transparent),
"contrast": light-dark(var(--cui-white), var(--cui-gray-900)),
),
),
$theme-colors
);Grayscale colors are also available as a Sass map. This map is not used to generate any utilities.
$grays: () !default;
// stylelint-disable-next-line scss/dollar-variable-default
$grays: defaults(
(
"025": gray("025"),
"050": gray("050"),
"100": gray("100"),
"200": gray("200"),
"300": gray("300"),
"400": gray("400"),
"500": gray("500"),
"600": gray("600"),
"700": gray("700"),
"800": gray("800"),
"900": gray("900"),
"950": gray("950"),
"975": gray("975")
),
$grays
);Background color opacities are applied through a map consumed by the utilities API, which mixes each color with transparent at the requested amount:
$utilities-bg-colors: map.merge(
theme-color-refs("bg"),
(
"black": var(--cui-black),
"white": var(--cui-white),
"body": var(--cui-bg-body)
)
) !default;
$utilities-bg-subtle: theme-color-refs("bg-subtle", "-subtle") !default;
$utilities-bg-muted: theme-color-refs("bg-muted", "-muted") !default;Sass mixins
No mixins are used to generate our background utilities, but we do have some additional mixins for other situations where you’d like to create your own gradients.
@mixin gradient-bg($color: null) {
background-color: $color;
@if $enable-gradients {
background-image: var(--cui-gradient);
}
}// Horizontal gradient, from left to right
//
// Creates two color stops, start and end, by specifying a color and position for each color stop.
@mixin gradient-x($start-color: var(--cui-gray-700), $end-color: var(--cui-gray-800), $start-percent: 0%, $end-percent: 100%) {
background-image: linear-gradient(to right, $start-color $start-percent, $end-color $end-percent);
}
// Vertical gradient, from top to bottom
//
// Creates two color stops, start and end, by specifying a color and position for each color stop.
@mixin gradient-y($start-color: var(--cui-gray-700), $end-color: var(--cui-gray-800), $start-percent: null, $end-percent: null) {
background-image: linear-gradient(to bottom, $start-color $start-percent, $end-color $end-percent);
}
@mixin gradient-directional($start-color: var(--cui-gray-700), $end-color: var(--cui-gray-800), $deg: 45deg) {
background-image: linear-gradient($deg, $start-color, $end-color);
}
@mixin gradient-x-three-colors($start-color: var(--cui-info-500), $mid-color: var(--cui-primary-500), $color-stop: 50%, $end-color: var(--cui-danger-500)) {
background-image: linear-gradient(to right, $start-color, $mid-color $color-stop, $end-color);
}
@mixin gradient-y-three-colors($start-color: var(--cui-info-500), $mid-color: var(--cui-primary-500), $color-stop: 50%, $end-color: var(--cui-danger-500)) {
background-image: linear-gradient($start-color, $mid-color $color-stop, $end-color);
}
@mixin gradient-radial($inner-color: var(--cui-gray-700), $outer-color: var(--cui-gray-800)) {
background-image: radial-gradient(circle, $inner-color, $outer-color);
}
@mixin gradient-striped($color: color-mix(in oklch, var(--cui-white) 15%, transparent), $angle: 45deg) {
background-image: linear-gradient($angle, $color 25%, transparent 25%, transparent 50%, $color 50%, $color 75%, transparent 75%, transparent);
}Utilities API
Background utilities are declared in our utilities API in scss/_utilities.scss. Learn how to use the utilities API.
"bg-color": (
property: (
--cui-bg: null,
background-color: var(--cui-bg),
),
class: bg,
values: map.merge(
map.merge($utilities-bg-colors, theme-token-refs($theme-bgs, "bg")),
(
"body-secondary": var(--cui-bg-3), // deprecated
"body-tertiary": var(--cui-bg-2), // deprecated
)
)
),
"bg-color-subtle": (
property: (
--cui-bg: null,
background-color: var(--cui-bg),
),
class: bg-subtle,
values: theme-color-refs("bg-subtle")
),
"bg-color-muted": (
property: (
--cui-bg: null,
background-color: var(--cui-bg),
),
class: bg-muted,
values: theme-color-refs("bg-muted")
),
"bg-opacity": (
class: bg,
property: background-color,
values: theme-opacity-values(--cui-bg)
),
// deprecated
"bg-color-subtle-legacy": (
property: (
--cui-bg: null,
background-color: var(--cui-bg),
),
class: bg,
values: $utilities-bg-subtle
),
// deprecated
"bg-color-muted-legacy": (
property: (
--cui-bg: null,
background-color: var(--cui-bg),
),
class: bg,
values: $utilities-bg-muted
),
// deprecated
"bg-opacity-legacy": (
class: bg-opacity,
property: background-color,
values: theme-opacity-values(--cui-bg, null, (10: .1, 15: .15, 25: .25, 50: .5, 75: .75, 100: 1))
),