Pictures

The pictures utility functions provide tools for generating responsive images with support for lazy loading and ACF integration.

Available Functions

cbo_acf_img($picture, $size, $urlset, $options)

Generates an HTML img tag from an ACF image array with support for responsive images.

Parameters:

$picture: ACF image array obtained via get_field().
$size: Image size to use (default: 'medium').
$urlset: Array of sizes and screen widths for srcset (default: null).
$options: Configuration options for the image tag.

Options:

echo: Display directly (true) or return HTML (false) (default: true).
placeholder: Use a placeholder if the image doesn't exist (default: true).
lazy: Enable lazy loading (default: true).
lazyClass: CSS class for lazy loading (default: 'lazy').
class: Additional CSS classes (default: '').
alt: Alternative text (default: null, uses image's alt text).

1// Basic usage
2$image = get_field('image');
3cbo_acf_img($image, 'medium');
4
5// With custom options
6cbo_acf_img($image, 'medium', null, [
7  'class' => 'featured-image',
8  'alt' => 'Custom description',
9  'lazy' => true
10]);
11
12// With responsive srcset
13cbo_acf_img($image, 'medium', [
14  ['thumbnail', 576],
15  ['medium', 768],
16  ['large', 1200],
17  ['sizes', '(min-width: 1200px) 1200px, 100vw']
18], [
19  'class' => 'responsive-image'
20]);

cbo_acf_picture($picture, $size, $urlset, $options)

Generates an HTML picture tag from an ACF image array, offering more precise control over responsive images.

Parameters:

$picture: ACF image array obtained via get_field().
$size: Image size to use (default: 'medium').
$urlset: Array of sizes and screen widths for sources (default: null).
$options: Configuration options for the picture tag.

Options:

Same as cbo_acf_img().

1// Using picture tag for art direction
2$image = get_field('image');
3cbo_acf_picture($image, 'medium', [
4  ['portrait', 576],  // Portrait format for mobile
5  ['landscape', 768], // Landscape format for tablet
6  ['large', 1200],    // Large image for desktop
7], [  768], // Landscape format for tablet
8  ['large', 1200],    // Large image for desktop
9], [
10  'class' => 'hero-image'
11]);

cbo_img($picture, $options, $urlset, $sizes)

Versatile function that generates an HTML img tag from different types of data (ID, URL, array).

Parameters:

$picture: WordPress image ID, URL, or array (default: null, uses featured image).
$options: Configuration options for the image tag.
$urlset: String srcset for responsive images (default: null).
$sizes: Attribute sizes for responsive images (default: null).

Options:

echo: Display directly (true) or return HTML (false) (default: true).
lazy: Enable lazy loading (default: true).
lazyClass: CSS class for lazy loading (default: 'lazy').
class: Additional CSS classes (default: '').
alt: Alternative text (default: '').
attr: Additional HTML attributes (default: '').

1// Using image ID
2cbo_img(123, [
3  'class' => 'logo',
4  'alt' => 'Company logo',
5  'lazy' => false
6]);
7
8// Using image URL
9cbo_img('https://example.com/image.jpg', [
10  'class' => 'banner',
11  'alt' => 'Banner image'
12]);
13
14// Using featured image
15cbo_img(null, [
16  'class' => 'featured-image',
17  'alt' => 'Featured image'
18]);
19
20// Using custom srcset
21$srcset = '123-300x200.jpg 300w, 123-600x400.jpg 600w, 123-900x600.jpg 900w';
22$sizes = '(max-width: 600px) 300px, (max-width: 1200px) 600px, 900px';
23cbo_img(123, ['class' => 'responsive-image'], $srcset, $sizes);

cbo_img_placeholder($echo, $style)

Generates an image placeholder when no image is available.

Parameters:

$echo: Display directly (true) or return HTML (false) (default: true).
$style: Inline CSS styles to apply to the placeholder (default: '').

1// Display placeholder with default style
2cbo_img_placeholder();
3
4// Display placeholder with custom style
5cbo_img_placeholder(true, 'width: 300px; height: 200px; background-color: #f5f5f5;');
6
7// Return placeholder for later use
8$placeholder = cbo_img_placeholder(false);
9echo '<div class="gallery">' . $placeholder . '</div>';

Lazy Loading

The system supports two methods of lazy loading:

Native

Uses the loading="lazy" attribute native to modern browsers.

Vanilla

Uses the data-src and data-srcset attributes that require JavaScript to function.

The method is configured via $cbo['assets']['lazyload']:

1// Configuration for native lazy loading
2$cbo['assets']['lazyload'] = 'native';
3
4// Configuration for vanilla lazy loading
5$cbo['assets']['lazyload'] = 'vanilla';

Usage Examples

Responsive Hero Image

1// Display a responsive hero image
2function display_hero_image() {
3  $hero_image = get_field('hero_image');
4  
5  if (!$hero_image) {
6    return;
7  }
8  
9  echo '<div class="hero-section">';
10  
11  // Use different image sizes for different screen widths
12  cbo_acf_picture($hero_image, 'large', [
13    ['medium', 768],    // Medium size for tablets
14    ['large', 1200],    // Large size for small desktops
15    ['full', 1920],     // Full size for large desktops
16  ], [
17    'class' => 'hero-image',
18    'alt' => get_field('hero_title')
19  ]);
20  
21  echo '<div class="hero-content">';
22  echo '<h1>' . get_field('hero_title') . '</h1>';
23  echo '<p>' . get_field('hero_subtitle') . '</p>';
24  echo '</div>';
25  echo '</div>';
26}
27
28// Usage
29display_hero_image();

Image Gallery

1// Display an image gallery
2function display_image_gallery() {
3  $gallery = get_field('gallery');
4  
5  if (!$gallery) {
6    return;
7  }
8  
9  echo '<div class="gallery-grid">';
10  
11  foreach ($gallery as $image) {
12    echo '<div class="gallery-item">';
13    
14    // Display thumbnail that links to full size image
15    echo '<a href="' . $image['url'] . '" class="gallery-link">';
16    cbo_acf_img($image, 'medium', null, [
17      'class' => 'gallery-thumbnail',
18      'alt' => $image['alt']
19    ]);
20    echo '</a>';
21    
22    if ($image['caption']) {
23      echo '<div class="caption">' . $image['caption'] . '</div>';
24    }
25    
26    echo '</div>';
27  }
28  
29  echo '</div>';
30}
31
32// Usage
33display_image_gallery();

Best Practices

Always provide alternative text for accessibility and SEO.
Use responsive images to optimize performance on all devices.
Enable lazy loading to improve page loading performance.
Specify image dimensions to prevent layout shifts during loading.
Use cbo_acf_picture for art direction (different image crops for different screen sizes).

← Admin Blocks →