Advanced Image Configuration Example

Learn how to configure responsive image sizes and optimize image handling with the Combo plugin.

Custom Image Sizes Configuration

This example demonstrates how to configure custom image sizes for different use cases:

config.yml

1# Advanced image configuration
2pictures:
3  yearmonth_folders: true  # Organize uploads by year/month
4
5  placeholder:             # Image placeholder settings
6    text: 'Image not available'
7    
8  thumbnail:               # Default thumbnail size
9    width: 150
10    height: 150
11    crop: true
12    
13  sizes:                   # Custom image sizes
14    # Content images
15    medium:
16      width: 768
17      height: 0
18      crop: false
19    large:
20      width: 1200
21      height: 0
22      crop: false
23      
24    # Hero images
25    hero-small:
26      width: 576
27      height: 300
28      crop: true
29    hero-medium:
30      width: 768
31      height: 400
32      crop: true
33    hero-large:
34      width: 1200
35      height: 500
36      crop: true
37    hero-xlarge:
38      width: 1920
39      height: 600
40      crop: true
41      
42    # Square images for cards and thumbnails
43    square-small:
44      width: 150
45      height: 150
46      crop: true
47    square-medium:
48      width: 300
49      height: 300
50      crop: true
51    square-large:
52      width: 600
53      height: 600
54      crop: true
55      
56    # Portrait images for team members
57    portrait-small:
58      width: 200
59      height: 300
60      crop: true
61    portrait-medium:
62      width: 400
63      height: 600
64      crop: true
65      
66    # Landscape images for featured posts
67    landscape-small:
68      width: 400
69      height: 300
70      crop: true
71    landscape-medium:
72      width: 800
73      height: 600
74      crop: true
75    
76    # Gallery images
77    gallery-thumbnail:
78      width: 200
79      height: 200
80      crop: true
81    gallery-full:
82      width: 1200
83      height: 800
84      crop: false

Using Custom Image Sizes

Here's how to use these custom image sizes in your theme:

Hero Section

1<?php
2// Get the hero image from ACF
3$hero_image = get_field('hero_image');
4
5// Use responsive image sizes with srcset
6cbo_acf_img($hero_image, 'hero-large', [
7  ['hero-small', 576],
8  ['hero-medium', 768],
9  ['hero-large', 1200],
10  ['hero-xlarge', 1920],
11  ['sizes', '100vw']
12], [
13  'class' => 'hero-image',
14  'lazy' => true
15]);
16?>

Team Member Grid

1<?php
2// Get team members
3$team_members = get_field('team_members');
4
5if ($team_members) {
6  echo '<div class="team-grid">';
7  
8  foreach ($team_members as $member) {
9    echo '<div class="team-member">';
10    
11    // Display team member photo
12    cbo_acf_img($member['photo'], 'portrait-medium', [
13      ['portrait-small', 576],
14      ['portrait-medium', 992]
15    ], [
16      'class' => 'team-member-photo',
17      'lazy' => true
18    ]);
19    
20    echo '<h3>' . $member['name'] . '</h3>';
21    echo '<p>' . $member['position'] . '</p>';
22    echo '</div>';
23  }
24  
25  echo '</div>';
26}
27?>

Featured Posts

1<?php
2// Get featured posts
3$featured_posts = get_field('featured_posts');
4
5if ($featured_posts) {
6  echo '<div class="featured-posts">';
7  
8  foreach ($featured_posts as $post) {
9    setup_postdata($post);
10    
11    echo '<div class="featured-post">';
12    
13    // Display featured image
14    if (has_post_thumbnail()) {
15      $featured_image_id = get_post_thumbnail_id();
16      
17      cbo_img($featured_image_id, [
18        'size' => 'landscape-medium',
19        'class' => 'featured-post-image',
20        'lazy' => true
21      ]);
22    }
23    
24    echo '<h3><a href="' . get_permalink() . '">' . get_the_title() . '</a></h3>';
25    echo '<div class="excerpt">' . get_the_excerpt() . '</div>';
26    echo '</div>';
27  }
28  
29  wp_reset_postdata();
30  echo '</div>';
31}
32?>

Image Gallery

1<?php
2// Get gallery images
3$gallery_images = get_field('gallery');
4
5if ($gallery_images) {
6  echo '<div class="gallery">';
7  
8  foreach ($gallery_images as $image) {
9    echo '<div class="gallery-item">';
10    
11    // Create a link to the full-size image
12    echo '<a href="' . $image['url'] . '" class="gallery-link" data-fancybox="gallery">';
13    
14    // Display thumbnail
15    cbo_acf_img($image, 'gallery-thumbnail', null, [
16      'class' => 'gallery-thumbnail',
17      'lazy' => true
18    ]);
19    
20    echo '</a>';
21    echo '</div>';
22  }
23  
24  echo '</div>';
25}
26?>

Optimizing Image Loading

Configure lazy loading for images to improve page load performance:

1# Configure lazy loading
2assets:
3  version: "1.0.0"
4  lazyload: true    # Enable native lazy loading
5
6# Or use vanilla JavaScript lazy loading
7# lazyload: 'vanilla'

When using vanilla JavaScript lazy loading, you'll need to include a lazy loading script:

1// Simple vanilla JavaScript lazy loading
2document.addEventListener('DOMContentLoaded', function() {
3  var lazyImages = [].slice.call(document.querySelectorAll('img.lazy'));
4  
5  if ('IntersectionObserver' in window) {
6    let lazyImageObserver = new IntersectionObserver(function(entries, observer) {
7      entries.forEach(function(entry) {
8        if (entry.isIntersecting) {
9          let lazyImage = entry.target;
10          lazyImage.src = lazyImage.dataset.src;
11          lazyImage.srcset = lazyImage.dataset.srcset;
12          lazyImage.classList.remove('lazy');
13          lazyImageObserver.unobserve(lazyImage);
14        }
15      });
16    });
17    
18    lazyImages.forEach(function(lazyImage) {
19      lazyImageObserver.observe(lazyImage);
20    });
21  } else {
22    // Fallback for browsers without IntersectionObserver support
23    let active = false;
24    
25    const lazyLoad = function() {
26      if (active === false) {
27        active = true;
28        
29        setTimeout(function() {
30          lazyImages.forEach(function(lazyImage) {
31            if ((lazyImage.getBoundingClientRect().top <= window.innerHeight && lazyImage.getBoundingClientRect().bottom >= 0) && getComputedStyle(lazyImage).display !== 'none') {
32              lazyImage.src = lazyImage.dataset.src;
33              lazyImage.srcset = lazyImage.dataset.srcset;
34              lazyImage.classList.remove('lazy');
35              
36              lazyImages = lazyImages.filter(function(image) {
37                return image !== lazyImage;
38              });
39              
40              if (lazyImages.length === 0) {
41                document.removeEventListener('scroll', lazyLoad);
42                window.removeEventListener('resize', lazyLoad);
43                window.removeEventListener('orientationchange', lazyLoad);
44              }
45            }
46          });
47          
48          active = false;
49        }, 200);
50      }
51    };
52    
53    document.addEventListener('scroll', lazyLoad);
54    window.addEventListener('resize', lazyLoad);
55    window.addEventListener('orientationchange', lazyLoad);
56  }
57});

Best Practices for Image Handling

Define image sizes based on their purpose and where they'll be used in your theme
Use descriptive names for custom image sizes
Enable lazy loading for images below the fold
Use srcset and sizes attributes for responsive images
Set appropriate crop parameters based on the image's purpose
Consider using WebP format for better compression (requires additional configuration)

← Basic Configuration Multilingual Setup →