Bootstrap Background Color, Image, Gradient and Opacity

Bootstrap’s background utilities give any element a theme color with one class: bg-primary, bg-success-subtle, bg-body-tertiary, and more. You can make the color transparent with bg-opacity-*, add a soft gradient with bg-gradient, or set a matching text color in the same class with text-bg-*. This guide covers every background class in Bootstrap 5.3, how they behave in dark mode, adding a background image, image overlays, custom gradients, and the CSS variables behind them.

Background color classes

Class	Color
bg-primary	Primary (blue by default)
bg-secondary	Secondary (gray)
bg-success	Success (green)
bg-danger	Danger (red)
bg-warning	Warning (yellow)
bg-info	Info (cyan)
bg-light	Light gray
bg-dark	Dark gray
bg-black	Black
bg-white	White
bg-transparent	Transparent

<div class="p-3 mb-2 bg-primary text-white">Primary background</div>
<div class="p-3 mb-2 bg-warning text-dark">Warning background</div>
<div class="p-3 mb-2 bg-dark text-white">Dark background</div>

Background classes don’t change the text color, so pair them with a text class, or use text-bg-* below.

Body and subtle backgrounds

Bootstrap 5.3 added classes that follow the color mode, so they work in both light and dark themes:

Class	Use
bg-body	The page background
bg-body-secondary	A slightly darker panel (lighter in dark mode)
bg-body-tertiary	A subtle panel, between body and secondary
bg-primary-subtle, bg-success-subtle, and the other colors	A pale tint of each theme color

<div class="p-4 bg-body-tertiary rounded-3">A subtle panel</div>

<div class="p-3 bg-success-subtle text-success-emphasis border border-success-subtle rounded">
  Your changes were saved.
</div>

bg-*-subtle pairs with text-*-emphasis and border-*-subtle for soft, readable callouts. Use bg-body-tertiary instead of bg-light for gray panels, because bg-light stays light in dark mode.

Background and text color together: text-bg-*

text-bg-* sets the background and a readable text color in one class, chosen for contrast:

<span class="badge text-bg-warning">Pending</span>
<div class="card text-bg-dark">
  <div class="card-body">Dark card with light text</div>
</div>

Available for every theme color: text-bg-primary, text-bg-secondary, text-bg-success, text-bg-danger, text-bg-warning, text-bg-info, text-bg-light, and text-bg-dark. The text is white on dark colors and black on light ones such as warning and info.

Background opacity

bg-opacity-* makes the background color transparent without affecting the text:

<div class="bg-primary bg-opacity-10 p-3">10%</div>
<div class="bg-primary bg-opacity-25 p-3">25%</div>
<div class="bg-primary bg-opacity-50 p-3">50%</div>
<div class="bg-primary bg-opacity-75 p-3">75%</div>
<div class="bg-primary p-3 text-white">100% (the default)</div>

The values are 10, 25, 50, 75, and 100. They work with the solid color classes, text-bg-*, bg-body, bg-body-secondary, bg-body-tertiary, bg-black, and bg-white, because those are built from RGB variables. They don’t work with the bg-*-subtle classes.

To fade the whole element, text included, use opacity-25, opacity-50, or opacity-75 instead.

For a custom opacity, set the variable inline:

<div class="bg-success p-3" style="--bs-bg-opacity: .15;">15% green</div>

Gradients

bg-gradient adds a subtle white-to-transparent gradient on top of a background color:

<div class="p-4 bg-primary bg-gradient text-white">Primary with a gradient</div>

The gradient is set by the --bs-gradient variable, linear-gradient(180deg, rgba(255, 255, 255, 0.15), rgba(255, 255, 255, 0)), so it’s a soft shine rather than a two-color blend. For a two-color gradient, write your own CSS:

.bg-brand-gradient {
  background-image: linear-gradient(135deg, #6f42c1 0%, #0d6efd 100%);
  color: #fff;
}

To add gradients to buttons and other components across the site, set $enable-gradients: true in Sass before importing Bootstrap. You can try a theme with gradients turned on in the bootstrap.build builder.

Background images

Bootstrap has no background image utilities, so set the image with inline styles or a class of your own:

<section class="py-5 text-white"
         style="background: url('/images/mountains.jpg') center / cover no-repeat;">
  <div class="container py-5">
    <h1 class="display-5 fw-bold">Plan your next trip</h1>
  </div>
</section>

center / cover scales the image to fill the section and crops the edges, which is usually what you want for a banner. For a background that stays still while the page scrolls, add background-attachment: fixed, though mobile browsers mostly ignore it.

Dark overlay for readable text

Text on a photo is hard to read without an overlay. Stack a semi-transparent layer between the image and the text with position classes:

<section class="position-relative text-white">
  <img src="/images/city.jpg" class="position-absolute top-0 start-0 w-100 h-100 object-fit-cover" alt="">
  <div class="position-absolute top-0 start-0 w-100 h-100 bg-black bg-opacity-50"></div>
  <div class="position-relative container py-5">
    <h1 class="display-5 fw-bold">Downtown offices</h1>
    <p class="lead">Desks from $199 a month.</p>
  </div>
</section>

Using an <img> with object-fit-cover instead of a CSS background lets you add loading, srcset, and alt like any other image. The position guide explains how the layers stack, and the hero section guide has more banner layouts.

Or do it in CSS with a gradient layered over the image:

.hero-overlay {
  background: linear-gradient(rgba(0, 0, 0, .5), rgba(0, 0, 0, .5)), url('/images/city.jpg') center / cover;
}

Backgrounds in dark mode

With data-bs-theme="dark", Bootstrap changes the body and subtle colors:

• bg-body, bg-body-secondary, and bg-body-tertiary turn dark.
• bg-*-subtle classes become dark tints.
• Solid colors such as bg-primary and bg-dark stay the same.
• bg-light and bg-white stay light, which is why they look wrong in a dark theme.

You can also set the theme on one element, for example a dark navbar on a light page, with data-bs-theme="dark" on that element. The dark mode guide shows how to switch themes.

Custom background colors

Each background class reads a CSS variable, so you can change a color site-wide:

:root {
  --bs-primary-rgb: 111, 66, 193;
  --bs-tertiary-bg: #f4f1fb;
  --bs-tertiary-bg-rgb: 244, 241, 251;
}

Solid classes use the -rgb variables so that bg-opacity-* works, so set those as comma-separated numbers. Changing --bs-primary-rgb alone doesn’t update buttons, which are compiled from Sass. For a full theme change, set $primary and the other Sass variables before importing Bootstrap; see how to customize Bootstrap colors and the Bootstrap colors guide.

To add your own background class that works with bg-opacity-*:

.bg-brand {
  --bs-bg-opacity: 1;
  background-color: rgba(111, 66, 193, var(--bs-bg-opacity)) !important;
}

Bootstrap 4 differences

• Bootstrap 4 had bg-* colors, bg-white, bg-transparent, and bg-gradient-* classes that only worked with $enable-gradients.
• Bootstrap 5 replaced those with a single bg-gradient class, and added bg-black, bg-opacity-* (5.1), text-bg-* (5.2), and the body and subtle backgrounds (5.3).

FAQ

How do I change the background color in Bootstrap 5?

Add a background class to the element, such as bg-primary, bg-success, bg-dark, or bg-body-tertiary. Background classes don’t change the text color, so pair them with text-white or use text-bg-primary to set both.

How do I make a background transparent in Bootstrap?

Use bg-transparent for no background, or bg-opacity-10, bg-opacity-25, bg-opacity-50, or bg-opacity-75 with a color class, such as bg-dark bg-opacity-50, for a semi-transparent color. The text stays fully opaque.

How do I add a background image in Bootstrap?

Bootstrap has no background image class, so use an inline style or your own CSS: style="background: url('image.jpg') center / cover no-repeat;". For readable text, add a dark overlay with bg-black bg-opacity-50 on an absolutely positioned layer.

How do I add a gradient background in Bootstrap?

Add bg-gradient to an element with a background color, such as bg-primary bg-gradient. It adds a soft white gradient on top. For a gradient between two colors, write a linear-gradient in your own CSS.

What is the difference between bg-light and bg-body-tertiary?

bg-light is always light gray, even in dark mode. bg-body-tertiary is a subtle gray in light mode and a dark gray in dark mode, so it works in both themes. Use bg-body-tertiary for panels and sections.

What does text-bg-primary do in Bootstrap?

text-bg-primary sets a primary background and a text color with enough contrast in one class. It was added in Bootstrap 5.2, and there are versions for every theme color, such as text-bg-warning and text-bg-dark.