Images

This section documents Bootstrap 5.x as implemented by the official Bootstrap project. No specific patch version is pinned. Unlike the other reference sections on this site, no single reference book underpins it: the content was generated with the assistance of AI from general knowledge of Bootstrap, and should be verified against the current official documentation at getbootstrap.com/docs before relying on it in production.

This section’s bibliography lists the reference material consulted while preparing these pages.

Bootstrap’s image handling is deliberately small: one responsive-sizing utility, one decorative-border utility, and a two-element component for images that need a caption. Everything else about an <img> — lazy loading, srcset, alt text — is left to plain HTML, since none of it is Bootstrap-specific.

Responsive images: .img-fluid

.img-fluid applies max-width: 100% and height: auto to an image, so it scales down to fit its parent container but never scales up past its natural size or overflows on a narrow viewport:

<img src="photo.jpg" class="img-fluid" alt="A responsive image that scales with its container">

Unlike some resets, Reboot does not set max-width/height on <img> — its only image-level rule is vertical-align: middle. That means .img-fluid is doing all of the real work here, not reasserting a default that’s already in place: an <img> without it can overflow its container on a narrow viewport, so a card, grid column, or any other container with a constrained width should add .img-fluid explicitly rather than relying on Reboot to have handled it.

Thumbnails: .img-thumbnail

.img-thumbnail adds a rounded 1px border, padding, and a subtle border-radius around an image — a lightweight frame, commonly used for a grid of gallery or avatar images:

<img src="photo.jpg" class="img-thumbnail" alt="An image styled with a rounded, padded border">

.img-thumbnail already includes max-width: 100%; height: auto; as part of its own rule set, so it does not need to be combined with .img-fluid — applying both is redundant, not additive.

Figures

For an image that needs a caption below it, Bootstrap provides a small figure component built on the native <figure>/<figcaption> elements: .figure on the wrapping <figure>, .figure-img on the <img> (usually paired with .img-fluid), and .figure-caption on the <figcaption>:

<figure class="figure">
  <img src="photo.jpg" class="figure-img img-fluid rounded" alt="A sample photo">
  <figcaption class="figure-caption">A caption for the above image.</figcaption>
</figure>

.figure-caption sets a smaller, muted font size and color for the caption text, matching the visual weight Bootstrap gives to other secondary/supporting text (see the .text-muted utility on Typography). Using the semantic <figure>/<figcaption> pair rather than a <div>/<p> also gives assistive technology an explicit association between the image and its caption, without any extra aria-* attributes needed.

Aligning a figure’s caption

Because .figure-caption is just a text utility applied to a block element, it composes with the ordinary text-alignment utilities from Typography:

<figure class="figure text-center">
  <img src="photo.jpg" class="figure-img img-fluid rounded" alt="A centered sample photo">
  <figcaption class="figure-caption">Centered caption text.</figcaption>
</figure>

Combining image utilities with other Bootstrap classes

Image classes are ordinary utility classes, so they combine freely with borders, shadows, and rounding utilities that are not image-specific:

<img
  src="photo.jpg"
  class="img-fluid rounded shadow-sm"
  alt="A rounded image with a subtle drop shadow">

  • .rounded (and its directional variants .rounded-top, .rounded-circle, etc.) applies border-radius.

  • .shadow-sm / .shadow / .shadow-lg applies a box-shadow of increasing size.

  • Border color utilities such as .border and .border-primary layer a colored border on top — see Colors for the full set of border-color utility classes.

Images inside the grid

An image with .img-fluid placed inside a grid column (see The Grid System) automatically shrinks and grows with that column as the viewport crosses breakpoints, with no additional media queries needed on the project’s own side:

<div class="row">
  <div class="col-md-4">
    <img src="thumb-1.jpg" class="img-fluid rounded" alt="Thumbnail one">
  </div>
  <div class="col-md-4">
    <img src="thumb-2.jpg" class="img-fluid rounded" alt="Thumbnail two">
  </div>
  <div class="col-md-4">
    <img src="thumb-3.jpg" class="img-fluid rounded" alt="Thumbnail three">
  </div>
</div>

Because .img-fluid only ever scales an image down, the source file’s actual resolution still matters for performance — serving a single very large image and relying on CSS scaling wastes bandwidth on small viewports. Responsive image loading (srcset, sizes, <picture>) is plain HTML and outside Bootstrap’s scope; the framework only controls how the image is displayed once loaded, not which file the browser fetches.

Image alignment

Because <img> renders as an inline element by default, the ordinary float and alignment utilities apply to it the same way they apply to any other inline or block content:

<!-- Float left/right -->
<img src="photo.jpg" class="img-fluid rounded float-start" alt="Floated left of surrounding text">
<img src="photo.jpg" class="img-fluid rounded float-end" alt="Floated right of surrounding text">

<!-- Centered: switch the image to a block element first, then center it as a block -->
<img src="photo.jpg" class="img-fluid rounded mx-auto d-block" alt="Centered image">

Centering deliberately takes two classes rather than one: .mx-auto (automatic left/right margin) only centers a block-level element with a defined width, so .d-block is needed first to switch the image away from its default inline display — an .mx-auto alone on an inline <img> has no visible effect.

Background images vs. <img>

Everything on this page concerns a real <img> element in the markup. A background image, set via CSS background-image on a <div> or similar container, is a different mechanism entirely and is not covered by .img-fluid, .img-thumbnail, or the figure component — those classes only ever target the <img> tag’s own box. Bootstrap intentionally provides no dedicated background-image utility; sizing and positioning a background image (background-size: cover, background-position: center) is plain CSS, chosen deliberately for cases such as a hero banner where the image is purely decorative and should not appear in the accessibility tree the way a real <img> (with meaningful alt text) does.

Common pitfalls

  • Missing or empty alt text. None of Bootstrap’s image classes affect accessibility — a meaningful, descriptive alt attribute (or alt="" for a genuinely decorative image) is still the author’s responsibility on every <img>, exactly as covered in the accessibility notes on Getting Started.

  • Applying .img-fluid to an image with an explicit width/height attribute set on the tag itself. The CSS max-width: 100% still wins visually, but the HTML width/height attributes are what the browser uses to reserve layout space before the image loads (avoiding layout shift) — leaving them off entirely, rather than fighting them with CSS, tends to produce the least surprising result.

  • Stacking .img-fluid and .img-thumbnail together, as noted above — harmless, but redundant, since .img-thumbnail already includes the fluid-sizing rule.

See the official Images documentation for the full class reference, including image alignment utilities.