Image Component

This component represents any image uploaded to the WP media library, including featured images for all content types. Functionality is also included for:

• Responsive image markup using both:
  • <img> with srcset and sizes.
  • <picture>/<source> for art direction.
• Determining if an image should be lazyloaded or not (lazyload implementation is up to you, though).
• Configurable handling of image sizes/positions.
• Integration with the Photon API to apply image transformations. Currently supported transforms:
  • w - set the width of an image
  • h - set the height of an image
  • crop - crop an image
  • resize - resize and crop an image to an exact width and height
  • fit - fit an image into a containing width and height while maintaining original aspect ratio
  • quality - modify compression quality of image
• Handling of intrinsic ratio sizing using CSS.

Using the component

Creating a new image component consists primarily of supplying the component with either a Post ID or an Attachemnt ID in combination with an optional string representing an image size and an optional boolean determining if <img> or <picture> attributes should be constructed. For example:

( new Image() )->configure( $attachment_or_post_id, 'large-feature' );

Below is more detailed documentation on the methods available:

• configure - Provide a Post ID or Attachment ID. Optionally provide an image size and a boolean for whether or not to render a <picture>. If no image size is provided, WordPress's default full image size will be used.
• set_post_id - Provide a Post ID. The thumbnail of that post will be used to create the image. You must use either this method or set_attachment_id for the Image component to function properly.
• set_attachment_id - Provide an Attachment ID. You must use either this method or set_post_id for the Image component to function properly.
• set_config_for_size - Provide an image size to use for creating the srcset attribute or <source> tags.
• set_url - Set a new URL for the image
• lazyload - Shortcut for configuring the lazyload config property. Pass a boolean to turn on or off.
• aspect_ratio - Set aspect ratio for use with CSS intrinsic ratio sizing. Pass false to this function to disable CSS sizing entirely.

In addition, there are three static methods for configuring the Image class functionality:

• register_sizes - Register image sizes and corresponding configurations (see configuration docs below). The class itself will provide configurations for WordPress's default image sizes: thumbnail, medium, and large.
• register_breakpoints - Register breakpoints for use in media attributes (see configuration docs below)
• register_fallback_image - Provide an ID corresponding to an Attachment to be used as a global fallback in case an image or attachment is missing or a provided image size is not configured.

Configuration

Some configuration is required to use the image component. You need to declare at least one image size and configure its corresponding transforms and descriptor using the register_sizes method of the Image class. Example:

/**
 * Register image sizes for use by the Image component.
 */
\WP_Components\Image::register_sizes( [
    'large-feature' => [
        'sources' => [
            [
                'transforms' => [
                    'resize' => [ 950, 627 ],
                ],
                'descriptor' => 949,
            ],
            [
                'transforms' => [
                    'resize' => [ 800, 528 ],
                ],
                'descriptor' => 800,
            ],
        ],
    ],
] );

In addition, if you need to use a <picture> element you'll need to register breakpoints and use them in the media property for each image source. The reason for this is <source> tags will be ignored if a media attribute is not provided. Example:

\WP_Components\Image::register_breakpoints( [
    'xl' => '80rem',
    'lg' => '64rem',
    'md' => '48rem',
    'sm' => '32rem',
] );

\WP_Components\Image::register_sizes( [
    'large-feature' => [
        'sources' => [
            [
                'transforms' => [
                    'resize' => [ 950, 627 ],
                ],
                'descriptor' => 949,
                'media' => [ 'min' => 'lg' ]
            ],
            [
                'transforms' => [
                    'resize' => [ 800, 528 ],
                ],
                'descriptor' => 800,
                'media' => [ 'max' => 'md' ]
            ],
        ],
    ],
] );

Below is a more detailed breakdown of each configuration properties when registering sizes:

• [size_string] - image size key. Used when calling set_config_for_size method before rendering the component.
  • sources - array of sources to include in srcset attribute in the case of an <img> tag, or <source> tags in the case of <picture>
    • transforms - array of Photon transformations to apply to this source. You can apply any number or combination of transforms per-source.
      • [transform_string] - configuration for Photon transforms. Any of the transforms listed in the first section of this document may be configured here.
    • descriptor - an integer representing a width descriptor for the image. This is required for the browser to determine which image source to choose (see documentation for srcset attribute)
    • media - an array describing the media conditions for which this source should be applied. Media has three options:
      • min - a string representing a breakpoint (taken from your registered breakpoints) for use as a min-width
      • max - a string representing a breakpoint (taken from your registered breakpoints) for use as a max-width
      • custom - a custom breakpoint value. If used, this should contain the full representation of the media query. For example, if you want both a min and max height you need to write out (min-height: 400px) and (max-height: 600px)
  • aspect_ratio - Aspect ratio represented as height / width or a decimal. This can be used to set intrinsic CSS on the resulting image markup. Set to false to bypass intrinsic sizing.
  • lazyload - Turn on or off lazyloading for this image size.
  • fallback_image_url - Set a size-specific fallback image. Useful if you have, for example, an avatar image that needs to have different fallback from all other images on the site.
  • retina - Turn on or off automatic handling of 2x image resolution for retina screens.

And when registering breakpoints:

• xl - name for the breakpoint, for use with the media min or max settings
• 80rem - breakpoint that will be supplied as the value for min-width or max-width

Support for WPCOM Thumbnail Editor

Since the Image component reflects the Photon API, we can use the WPCOM Thumbnail Editor,

https://github.com/Automattic/wpcom-thumbnail-editor

// Register WPCOM Thumbnail Editor crops.
\WP_Components\Image::register_crop_sizes(
	[
		'Search Results Item' => [
			'search-results-item' => [
				'height' => 212,
				'width'  => 281,
			],
		],
		'Term Archive List Item' => [
			'term-archive-content-list-item' => [
				'height' => 503,
				'width'  => 906,
			],
		],
		'Square' => [
			'content-list-item' => [
				'width'  => 100,
				'height' => 100,
			],
		],
		'16:9' => [
			'hero' => [
				'height' => 1080,
				'width'  => 1920,
			],
			'article-featured-image' => [
				'width'  => 701,
				'height' => 394,
			],
		],
		'2:3' => [
			'curated_content' => [
				'width'  => 252,
				'height' => 168,
			],
			'curated_content_single' => [
				'width'  => 697,
				'height' => 465,
			],
			'grid' => [
				'width'  => 234,
				'height' => 156,
			],
			'feature-module' => [
				'width'  => 500,
				'height' => 333,
			],
			'gallery' => [
				'width'  => 578,
				'height' => 385,
			],
		],
	]
);