Title: img_caption_shortcode
Published: April 25, 2014
Last modified: February 24, 2026

---

# img_caption_shortcode( array $attr, string $content ): string

## In this article

 * [Description](https://developer.wordpress.org/reference/functions/img_caption_shortcode/?output_format=md#description)
 * [Parameters](https://developer.wordpress.org/reference/functions/img_caption_shortcode/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/functions/img_caption_shortcode/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/functions/img_caption_shortcode/?output_format=md#source)
 * [Hooks](https://developer.wordpress.org/reference/functions/img_caption_shortcode/?output_format=md#hooks)
 * [Related](https://developer.wordpress.org/reference/functions/img_caption_shortcode/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/functions/img_caption_shortcode/?output_format=md#changelog)

[ Back to top](https://developer.wordpress.org/reference/functions/img_caption_shortcode/?output_format=md#wp--skip-link--target)

Builds the Caption shortcode output.

## 󠀁[Description](https://developer.wordpress.org/reference/functions/img_caption_shortcode/?output_format=md#description)󠁿

Allows a plugin to replace the content that would otherwise be returned. The filter
is [‘img_caption_shortcode’](https://developer.wordpress.org/reference/hooks/img_caption_shortcode/)
and passes an empty string, the attr parameter and the content parameter values.

The supported attributes for the shortcode are ‘id’, ‘caption_id’, ‘align’, ‘width’,‘
caption’, and ‘class’.

## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/img_caption_shortcode/?output_format=md#parameters)󠁿

 `$attr`arrayrequired

Attributes of the caption shortcode.

 * `id` string
 * ID of the image and caption container element, i.e. `<figure>` or `<div>`.
 * `caption_id` string
 * ID of the caption element, i.e. `<figcaption>` or `<p>`.
 * `align` string
 * Class name that aligns the caption. Default `'alignnone'`. Accepts `'alignleft'`,`'
   aligncenter'`, alignright’, `'alignnone'`.
 * `width` int
 * The width of the caption, in pixels.
 * `caption` string
 * The caption text.
 * `class` string
 * Additional class name(s) added to the caption container.

`$content`stringoptional

Shortcode content. Default empty string.

## 󠀁[Return](https://developer.wordpress.org/reference/functions/img_caption_shortcode/?output_format=md#return)󠁿

 string HTML content to display the caption.

## 󠀁[Source](https://developer.wordpress.org/reference/functions/img_caption_shortcode/?output_format=md#source)󠁿

    ```php
    function img_caption_shortcode( $attr, $content = '' ) {
    	// New-style shortcode with the caption inside the shortcode with the link and image tags.
    	if ( ! isset( $attr['caption'] ) ) {
    		if ( preg_match( '#((?:<a [^>]+>\s*)?<img [^>]+>(?:\s*</a>)?)(.*)#is', $content, $matches ) ) {
    			$content         = $matches[1];
    			$attr['caption'] = trim( $matches[2] );
    		}
    	} elseif ( str_contains( $attr['caption'], '<' ) ) {
    		$attr['caption'] = wp_kses( $attr['caption'], 'post' );
    	}

    	/**
    	 * Filters the default caption shortcode output.
    	 *
    	 * If the filtered output isn't empty, it will be used instead of generating
    	 * the default caption template.
    	 *
    	 * @since 2.6.0
    	 *
    	 * @see img_caption_shortcode()
    	 *
    	 * @param string $output  The caption output. Default empty.
    	 * @param array  $attr    Attributes of the caption shortcode.
    	 * @param string $content The image element, possibly wrapped in a hyperlink.
    	 */
    	$output = apply_filters( 'img_caption_shortcode', '', $attr, $content );

    	if ( ! empty( $output ) ) {
    		return $output;
    	}

    	$atts = shortcode_atts(
    		array(
    			'id'         => '',
    			'caption_id' => '',
    			'align'      => 'alignnone',
    			'width'      => '',
    			'caption'    => '',
    			'class'      => '',
    		),
    		$attr,
    		'caption'
    	);

    	$atts['width'] = (int) $atts['width'];

    	if ( $atts['width'] < 1 || empty( $atts['caption'] ) ) {
    		return $content;
    	}

    	$id          = '';
    	$caption_id  = '';
    	$describedby = '';

    	if ( $atts['id'] ) {
    		$atts['id'] = sanitize_html_class( $atts['id'] );
    		$id         = 'id="' . esc_attr( $atts['id'] ) . '" ';
    	}

    	if ( $atts['caption_id'] ) {
    		$atts['caption_id'] = sanitize_html_class( $atts['caption_id'] );
    	} elseif ( $atts['id'] ) {
    		$atts['caption_id'] = 'caption-' . str_replace( '_', '-', $atts['id'] );
    	}

    	if ( $atts['caption_id'] ) {
    		$caption_id  = 'id="' . esc_attr( $atts['caption_id'] ) . '" ';
    		$describedby = 'aria-describedby="' . esc_attr( $atts['caption_id'] ) . '" ';
    	}

    	$class = trim( 'wp-caption ' . $atts['align'] . ' ' . $atts['class'] );

    	$html5 = current_theme_supports( 'html5', 'caption' );
    	// HTML5 captions never added the extra 10px to the image width.
    	$width = $html5 ? $atts['width'] : ( 10 + $atts['width'] );

    	/**
    	 * Filters the width of an image's caption.
    	 *
    	 * By default, the caption is 10 pixels greater than the width of the image,
    	 * to prevent post content from running up against a floated image.
    	 *
    	 * @since 3.7.0
    	 *
    	 * @see img_caption_shortcode()
    	 *
    	 * @param int    $width    Width of the caption in pixels. To remove this inline style,
    	 *                         return zero.
    	 * @param array  $atts     Attributes of the caption shortcode.
    	 * @param string $content  The image element, possibly wrapped in a hyperlink.
    	 */
    	$caption_width = apply_filters( 'img_caption_shortcode_width', $width, $atts, $content );

    	$style = '';

    	if ( $caption_width ) {
    		$style = 'style="width: ' . (int) $caption_width . 'px" ';
    	}

    	if ( $html5 ) {
    		$html = sprintf(
    			'<figure %s%s%sclass="%s">%s%s</figure>',
    			$id,
    			$describedby,
    			$style,
    			esc_attr( $class ),
    			do_shortcode( $content ),
    			sprintf(
    				'<figcaption %sclass="wp-caption-text">%s</figcaption>',
    				$caption_id,
    				$atts['caption']
    			)
    		);
    	} else {
    		$html = sprintf(
    			'<div %s%sclass="%s">%s%s</div>',
    			$id,
    			$style,
    			esc_attr( $class ),
    			str_replace( '<img ', '<img ' . $describedby, do_shortcode( $content ) ),
    			sprintf(
    				'<p %sclass="wp-caption-text">%s</p>',
    				$caption_id,
    				$atts['caption']
    			)
    		);
    	}

    	return $html;
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-includes/media.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-includes/media.php#L2527)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-includes/media.php#L2527-L2656)

## 󠀁[Hooks](https://developer.wordpress.org/reference/functions/img_caption_shortcode/?output_format=md#hooks)󠁿

 [apply_filters( ‘img_caption_shortcode’, string $output, array $attr, string $content )](https://developer.wordpress.org/reference/hooks/img_caption_shortcode/)

Filters the default caption shortcode output.

 [apply_filters( ‘img_caption_shortcode_width’, int $width, array $atts, string $content )](https://developer.wordpress.org/reference/hooks/img_caption_shortcode_width/)

Filters the width of an image’s caption.

## 󠀁[Related](https://developer.wordpress.org/reference/functions/img_caption_shortcode/?output_format=md#related)󠁿

| Uses | Description | 
| [sanitize_html_class()](https://developer.wordpress.org/reference/functions/sanitize_html_class/)`wp-includes/formatting.php` |

Sanitizes an HTML classname to ensure it only contains valid characters.

  | 
| [wp_kses()](https://developer.wordpress.org/reference/functions/wp_kses/)`wp-includes/kses.php` |

Filters text content and strips out disallowed HTML.

  | 
| [shortcode_atts()](https://developer.wordpress.org/reference/functions/shortcode_atts/)`wp-includes/shortcodes.php` |

Combines user attributes with known attributes and fill in defaults when needed.

  | 
| [do_shortcode()](https://developer.wordpress.org/reference/functions/do_shortcode/)`wp-includes/shortcodes.php` |

Searches content for shortcodes and filter shortcodes through their hooks.

  | 
| [current_theme_supports()](https://developer.wordpress.org/reference/functions/current_theme_supports/)`wp-includes/theme.php` |

Checks a theme’s support for a given feature.

  | 
| [esc_attr()](https://developer.wordpress.org/reference/functions/esc_attr/)`wp-includes/formatting.php` |

Escaping for HTML attributes.

  | 
| [apply_filters()](https://developer.wordpress.org/reference/functions/apply_filters/)`wp-includes/plugin.php` |

Calls the callback functions that have been added to a filter hook.

  |

[Show 3 more](https://developer.wordpress.org/reference/functions/img_caption_shortcode/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/functions/img_caption_shortcode/?output_format=md#)

| Used by | Description | 
| [WP_Widget_Media_Image::render_media()](https://developer.wordpress.org/reference/classes/wp_widget_media_image/render_media/)`wp-includes/widgets/class-wp-widget-media-image.php` |

Render the media on the frontend.

  |

## 󠀁[Changelog](https://developer.wordpress.org/reference/functions/img_caption_shortcode/?output_format=md#changelog)󠁿

| Version | Description | 
| [5.9.0](https://developer.wordpress.org/reference/since/5.9.0/) | The `$content` parameter default value changed from `null` to `''`. | 
| [5.1.0](https://developer.wordpress.org/reference/since/5.1.0/) | The `caption_id` attribute was added. | 
| [3.9.0](https://developer.wordpress.org/reference/since/3.9.0/) | The `class` attribute was added. | 
| [2.6.0](https://developer.wordpress.org/reference/since/2.6.0/) | Introduced. |

## User Contributed Notes

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fimg_caption_shortcode%2F)
before being able to contribute a note or feedback.