img

The image element embeds responsive images with automatic sizing, lazy loading support, and visual variants for different use cases.

Description

The <img> element is the primary way to embed images in HTML. Vanilla Breeze styles images to be responsive by default, constraining them to their container width while maintaining aspect ratio. Additional variant classes provide shapes, borders, and aspect ratio control.

Images are block-level elements with max-inline-size: 100% and block-size: auto, ensuring they never overflow their container while preserving their natural proportions.

When to Use

  • Content images - Photos, illustrations, and graphics that are part of the content
  • Avatars - User profile pictures using the .circle variant
  • Thumbnails - Small preview images with borders
  • Hero images - Large banner images using .full variant
  • Product images - E-commerce product photos with consistent aspect ratios

When to Use Other Elements

  • Use <picture> for art direction or serving different formats
  • Use <figure> to wrap images that need captions
  • Use <svg> for icons and vector graphics
  • Use CSS background-image for decorative images that don't convey content

Variants

Default

Images are block-level and constrained to their container width.

A scenic landscape photograph
<img src="photo.jpg" alt="A scenic landscape photograph" />

.rounded

Applies medium border radius for softer edges.

Rounded image example
<img src="photo.jpg" alt="..." class="rounded" />

.circle

Creates a circular crop with 1:1 aspect ratio. Ideal for avatars and profile pictures.

Small avatar Medium avatar Large avatar
<img src="avatar.jpg" alt="User name" class="circle" style="max-inline-size: 96px;" />

.thumbnail

Adds padding and a subtle border for gallery-style thumbnails.

Thumbnail 1 Thumbnail 2 Thumbnail 3
<img src="thumb.jpg" alt="..." class="thumbnail" />

.full

Forces the image to fill its container width completely.

Full width banner image
<img src="banner.jpg" alt="..." class="full" />

Aspect Ratios

Force consistent aspect ratios with automatic cropping via object-fit: cover.

.ratio-square Square aspect .ratio-video (16:9) Video aspect .ratio-portrait (3:4) Portrait aspect .ratio-landscape (4:3) Landscape aspect
Class Aspect Ratio Use Case
.ratio-square 1:1 Profile photos, app icons
.ratio-video 16:9 Video thumbnails, hero images
.ratio-portrait 3:4 Book covers, portraits
.ratio-landscape 4:3 Classic photo format

Object Fit

Control how images fit within constrained dimensions.

.contain

Scales to fit within bounds, preserving aspect ratio. May show letterboxing.

Contain example
.cover

Fills container completely, cropping as needed.

Cover example
<!-- Contain: letterbox to fit --> <img src="tall.jpg" alt="..." class="contain" style="max-block-size: 200px;" /> <!-- Cover: crop to fill --> <img src="photo.jpg" alt="..." class="cover" style="block-size: 200px; inline-size: 100%;" />

Lazy Loading

Native lazy loading defers loading images until they approach the viewport, improving initial page load performance.

Lazy loaded image
<!-- Lazy load images below the fold --> <img src="photo.jpg" alt="..." loading="lazy" /> <!-- Eager load critical above-the-fold images --> <img src="hero.jpg" alt="..." loading="eager" />

Loading States

Lazy-loaded images display a subtle background color while loading. Broken or missing images show a placeholder.

Loading Loading placeholder

Accessibility

Alt Text Guidelines

Every image must have an alt attribute. The content depends on the image's purpose:

Image Type Alt Text Approach Example
Informative Describe the content and meaning alt="Golden retriever playing fetch in a park"
Functional Describe the action or destination alt="Submit form"
Decorative Empty alt attribute alt=""
Complex Brief summary + detailed description nearby alt="Q3 sales chart. Details in table below."

Best Practices

  • Keep alt text concise (under 125 characters when possible)
  • Don't start with "Image of" or "Picture of" - screen readers announce this
  • Include relevant text that appears in the image
  • For decorative images, use alt="" (not omitting the attribute)
  • Use role="presentation" for purely decorative images
<!-- Informative image --> <img src="team.jpg" alt="The engineering team celebrating the product launch" /> <!-- Decorative image --> <img src="divider.png" alt="" role="presentation" /> <!-- Functional image (link) --> <a href="/profile"> <img src="avatar.jpg" alt="View your profile" /> </a>

Related Elements

  • <picture> - Art direction and format switching with multiple sources
  • <source> - Define image sources within picture element
  • <figure> - Semantic wrapper for images with captions
  • <figcaption> - Caption text for figures
  • <svg> - Vector graphics and icons

CSS Reference

Styles defined in /src/native-elements/image/styles.css

Selector Properties
img max-inline-size: 100%; block-size: auto; display: block;
img.rounded border-radius: var(--radius-m);
img.circle border-radius: var(--radius-full); aspect-ratio: 1; object-fit: cover;
img.thumbnail padding; background; border; border-radius;
img.contain object-fit: contain;
img.cover object-fit: cover;
img[loading="lazy"] background: var(--color-surface-raised);