Using WordPress ’embed_handler_html’ PHP filter

by

The embed_handler_html WordPress PHP filter allows you to modify the HTML output of an embedded media item in a WordPress post or page.

Usage

add_filter('embed_handler_html', 'my_custom_function', 10, 3);

function my_custom_function($return, $url, $attr) {
    // your custom code here
    return $return;
}

Parameters

  • $return (string|false) – The HTML result of the shortcode, or false on failure.
  • $url (string) – The embed URL.
  • $attr (array) – An array of shortcode attributes.

More information

See WordPress Developer Resources: embed_handler_html

Examples

Add a custom class to embedded videos

Add a custom CSS class to all embedded videos for styling purposes.

add_filter('embed_handler_html', 'add_custom_class_to_embeds', 10, 3);

function add_custom_class_to_embeds($return, $url, $attr) {
    // Add a custom class to the embedded media
    $return = str_replace('<iframe', '<iframe class="my-custom-class"', $return);
    return $return;
}

Wrap embeds in a responsive container

Wrap embedded media in a div container with a responsive class.

add_filter('embed_handler_html', 'wrap_embeds_in_responsive_container', 10, 3);

function wrap_embeds_in_responsive_container($return, $url, $attr) {
    // Wrap the embed in a responsive container
    $return = '<div class="responsive-embed">' . $return . '</div>';
    return $return;
}

Add a custom attribute to embedded iframes

Add a custom attribute to all embedded iframes, such as “sandbox” for security purposes.

add_filter('embed_handler_html', 'add_custom_attribute_to_iframes', 10, 3);

function add_custom_attribute_to_iframes($return, $url, $attr) {
    // Add a custom attribute to the iframe
    $return = str_replace('<iframe', '<iframe sandbox="allow-scripts"', $return);
    return $return;
}

Remove specific URL parameters from embeds

Remove URL parameters, such as “autoplay”, from embedded media items.

add_filter('embed_handler_html', 'remove_autoplay_parameter', 10, 3);

function remove_autoplay_parameter($return, $url, $attr) {
    // Remove autoplay parameter from the embedded media URL
    $return = preg_replace('/autoplay=1/', '', $return);
    return $return;
}

Modify the maximum width of embeds

Change the maximum width of all embedded media items.

add_filter('embed_handler_html', 'modify_max_width_of_embeds', 10, 3);

function modify_max_width_of_embeds($return, $url, $attr) {
    // Set the maximum width to 800px
    $return = preg_replace('/width="\d+"/', 'width="800"', $return);
    return $return;
}