# Vue Background Utilities

> Convey meaning through `background-color` and add decoration with gradients.

## 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](https://coreui.io/vue/docs/utilities/colors/).

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.

```html
<div class="p-4 mb-3 text-bg-${c.name}">.bg-${c.name}</div>
<div class="p-4 mb-3 bg-muted-${c.name} fg-emphasis-${c.name}">.bg-muted-${c.name}</div>
<div class="p-4 mb-3 bg-subtle-${c.name} fg-emphasis-${c.name}">.bg-subtle-${c.name}</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.

```html
<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);`.

<div class="p-4 mb-3 text-bg-primary bg-gradient">.bg-primary.bg-gradient</div>
<div class="p-4 mb-3 text-bg-secondary bg-gradient">.bg-secondary.bg-gradient</div>
<div class="p-4 mb-3 text-bg-success bg-gradient">.bg-success.bg-gradient</div>
<div class="p-4 mb-3 text-bg-danger bg-gradient">.bg-danger.bg-gradient</div>
<div class="p-4 mb-3 text-bg-warning bg-gradient">.bg-warning.bg-gradient</div>
<div class="p-4 mb-3 text-bg-info bg-gradient">.bg-info.bg-gradient</div>
<div class="p-4 mb-3 bg-black bg-gradient fg-white">.bg-black.bg-gradient</div>

## 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.

```css
.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.

```html
<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](https://coreui.io/vue/docs/customize/css-variables/) (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.

```scss
$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:

```scss
$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.

```scss
$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.**

```scss
$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:

```scss
$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.

```scss
@mixin gradient-bg($color: null) {
  background-color: $color;

  @if $enable-gradients {
    background-image: var(--cui-gradient);
  }
}
```

```scss
// 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.](https://coreui.io/vue/docs/utilities/api/#using-the-api)

```scss
"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))
),
```