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 and Aspect Ratios

Vanilla Breeze provides variant classes for common image treatments: .rounded, .circle, .thumbnail, .full, and aspect ratio classes like .ratio-square, .ratio-video, .ratio-portrait, and .ratio-landscape.

Variant Classes

Aspect Ratio Classes

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.

Lazy Loading

Native lazy loading defers loading images until they approach the viewport, improving initial page load performance. Lazy-loaded images display a subtle background color while loading.

Image Links

When an <img> is the direct child of an <a>, Vanilla Breeze automatically removes the underline decoration via a:has(> img) { text-decoration: none }. This prevents an unsightly underline bar beneath linked images.

See the <a> element docs for more on link styling and auto-detected link types.

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

Related

  • <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
  • <a> - Image links with automatic underline removal
  • <layout-card> - Cards that commonly contain images
  • <compare-surface> - Before/after image comparison slider

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);
↑