ComboDocs

Images

The images utility functions provide a comprehensive set of tools for handling images in WordPress, with advanced support for responsive images, lazy loading, and ACF integration.

Main Functions

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

Generates an <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.
  • $options: Configuration options for the image tag.

Options:

  • echo: Display directly (true) or return HTML (false).
  • placeholder: Use a placeholder if the image doesn't exist.
  • lazy: Enable lazy loading.
  • lazyClass: CSS class for lazy loading.
  • class: Additional CSS classes.
  • alt: Alternative text.
1
// Basic usage
2
$image = get_field('image');
3
cbo_acf_img($image, 'medium');
4
5
// With custom options
6
cbo_acf_img($image, 'medium', null, [
7
    'class' => 'featured-image',
8
    'alt' => 'Custom description',
9
    'lazy' => true
10
]);

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

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

The <picture> tag allows you to specify different image sources for different screen sizes, providing more control than the srcset attribute of the <img> tag.

1
// Using picture tag for art direction
2
$image = get_field('image');
3
cbo_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
], [
8
    'class' => 'hero-image'
9
]);

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

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

Supported data types for $picture:

  • WordPress image ID (integer)
  • Image URL (string)
  • Array [url, width, height]
  • Null (uses the featured image of the current post)
1
// Using image ID
2
cbo_img(123, [
3
    'class' => 'logo',
4
    'alt' => 'Company logo',
5
    'lazy' => false
6
]);
7
8
// Using image URL
9
cbo_img('https://example.com/image.jpg', [
10
    'class' => 'banner',
11
    'alt' => 'Banner image'
12
]);
13
14
// Using custom srcset
15
$srcset = '123-300x200.jpg 300w, 123-600x400.jpg 600w, 123-900x600.jpg 900w';
16
$sizes = '(max-width: 600px) 300px, (max-width: 1200px) 600px, 900px';
17
cbo_img(123, ['class' => 'responsive-image'], $srcset, $sizes);

cbo_img_placeholder($echo, $style)

Generates an image placeholder when no image is available.

1
// Display placeholder with custom style
2
cbo_img_placeholder(true, 'width: 300px; height: 200px; background-color: #f5f5f5;');
3
4
// Return placeholder for later use
5
$placeholder = cbo_img_placeholder(false);
6
echo '<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';

Advanced Usage Examples

ACF Image with srcset

1
$image = get_field('image');
2
cbo_acf_img($image, 'medium', [
3
    ['thumbnail', 576],
4
    ['medium', 768],
5
    ['large', 1200],
6
    ['sizes', '(min-width: 1200px) 1200px, 100vw']
7
], [
8
    'lazy' => true,
9
    'class' => 'featured-image responsive'
10
]);

Custom Placeholder Text

The text displayed in the placeholder can be configured and translated:

1
$cbo['pictures']['placeholder']['text'] = 'Image not available';

Best Practices for Images

  • 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.