Responsive Images

The CSS Element Queries library includes built-in responsive image functionality that automatically switches image sources based on container dimensions. This feature works without JavaScript configuration and provides smooth, performance-optimized image loading.

Capabilities

Responsive Image Container

Creates an intelligent image container that switches between different image sources based on the container's width, providing optimal images for different sizes without layout shifts.

<!-- Responsive image container -->
<div data-responsive-image>
    <img data-src="http://example.com/small.jpg"/>
    <img min-width="400" data-src="http://example.com/medium.jpg"/>
    <img min-width="800" data-src="http://example.com/large.jpg"/>
</div>

<!-- Alternative attribute syntax -->
<div responsive-image>
    <img url="http://example.com/small.jpg"/>
    <img data-min-width="400" url="http://example.com/medium.jpg"/>
    <img data-min-width="800" url="http://example.com/large.jpg"/>
</div>

How Responsive Images Work

1. Default Image: The first <img> element without a min-width attribute serves as the default/fallback image
2. Breakpoint Images: Additional <img> elements with min-width attributes define images for different container sizes
3. Automatic Switching: The library automatically shows the appropriate image based on the container's current width
4. Performance Optimization: Images are preloaded in memory before switching to prevent flash of missing content
5. Smooth Transitions: Only the visible image is displayed at any time, others are hidden with display: none

Attributes

Container Attributes

• data-responsive-image or responsive-image - Marks a <div> as a responsive image container

Image Attributes

• data-src or url - The image source URL to load when this image becomes active
• min-width or data-min-width - Minimum container width (in pixels) required for this image to be shown

Usage Examples

Basic Responsive Image

<div data-responsive-image>
    <!-- Default image for containers under 400px wide -->
    <img data-src="https://placehold.it/350x150"/>
    
    <!-- Medium image for containers 400px+ wide -->
    <img min-width="400" data-src="https://placehold.it/700x300"/>
    
    <!-- Large image for containers 800px+ wide -->
    <img min-width="800" data-src="https://placehold.it/1400x600"/>
</div>

Multiple Breakpoints

<div responsive-image>
    <!-- Mobile: default -->
    <img url="images/hero-mobile.jpg"/>
    
    <!-- Tablet: 600px+ -->
    <img data-min-width="600" url="images/hero-tablet.jpg"/>
    
    <!-- Desktop: 1024px+ -->
    <img data-min-width="1024" url="images/hero-desktop.jpg"/>
    
    <!-- Large desktop: 1440px+ -->
    <img data-min-width="1440" url="images/hero-large.jpg"/>
</div>

Art Direction

<div data-responsive-image>
    <!-- Portrait crop for narrow containers -->
    <img data-src="images/portrait-crop.jpg"/>
    
    <!-- Landscape crop for wide containers -->
    <img min-width="500" data-src="images/landscape-crop.jpg"/>
</div>

CSS Styling

The library automatically applies these CSS rules for responsive image containers:

[responsive-image] > img, 
[data-responsive-image] > img {
    overflow: hidden; 
    padding: 0;
    width: 100%;
}

You can add additional styling as needed:

.hero-container[data-responsive-image] {
    height: 300px;
    position: relative;
}

.hero-container img {
    height: 100%;
    object-fit: cover;
    transition: opacity 0.3s ease;
}

Performance Characteristics

• Preloading: Images are loaded in memory before switching to prevent content flashes
• Lazy Switching: Only switches images when container size actually changes
• Memory Efficient: Only one image is visible at a time, others are hidden
• Event-driven: Uses ResizeSensor for efficient resize detection without polling
• No FOUC: Flash of unstyled content is prevented through intelligent loading

Browser Compatibility

• IE7+
• All modern browsers
• Works with responsive layouts and CSS Grid/Flexbox
• Compatible with CSS transitions and animations

Implementation Notes

• Responsive image containers automatically get a ResizeSensor attached
• The default image is shown initially while other images preload
• Images are selected based on exact pixel width comparison
• Container padding and borders are included in width calculations
• Works with dynamically added responsive image containers

Integration with Element Queries

Responsive images work seamlessly alongside CSS element queries:

<div class="widget" data-responsive-image>
    <img data-src="widget-small.jpg"/>
    <img min-width="400" data-src="widget-large.jpg"/>
</div>

.widget {
    padding: 10px;
    background: #f0f0f0;
}

.widget[min-width~="400px"] {
    padding: 20px;
    background: #e0e0e0;
}

The container will have both responsive images and element query attributes applied simultaneously.