New filter to modify content images in WordPress 6.0

WordPress 6.0 introduces a new filterFilter Filters are one of the two types of Hooks They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output.  wp_content_img_tag to allow adjustment of images in a blob of HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. content, most prominently post content via the_content filter.

WordPress 5.5 originally introduced the wp_filter_content_tags() function to modify certain elements, primarily images, in a blob of HTML content. Prior to the WordPress 6.0 release, it was not possible to alter these image tags without duplicating the complex regex logic in the wp_filter_content_tags() function. This increased complexity and overhead. The new wp_content_img_tag filter solves this problem.

How to use the filter

The new wp_content_img_tag filter passes the following parameters:

  • string $filtered_image: The full img tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.) with attributes that will replace the source image tag.
  • string $context: Additional context, like the current filter name or the function name from where this was called.
  • int $attachment_id: The image attachment ID. May be 0 in case the image is not an attachment.

The filter must return a string which will then replace the img tag passed to the filter.


Here is an example in which the new filter is used to add a border-color style attribute to every image tag in the content.

function myplugin_img_tag_add_border_color( $filtered_image, $context, $attachment_id ) {
	$style = 'border-color: #cccccc;';

	$filtered_image = str_replace( '<img ', '<img style="' . $style . '" ', $filtered_image );

	return $filtered_image;
add_filter( 'wp_content_img_tag', 'myplugin_img_tag_add_border_color', 10, 3 );

The wp_filter_content_tags() function was originally introduced to facilitate lazy-loading support for images and has since become the standard approach for modifying in-content images for various performance enhancements. The new wp_content_img_tag filter expands these capabilities by giving control to pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the Plugin Directory or can be cost-based plugin from a third-party developers to add their own customizations.

For more context on the new filter, implementation see #55347.

Props to @flixos90 , @kkautzman, and @milana_cap for review and proofreading.

#6-0, #dev-notes, #dev-notes-6-0, #performance