WordPress allows you to embed content from platforms like YouTube, social media, and more. However, these embeds may not always match your theme’s design. You can customize WordPress embeds to ensure a seamless look throughout your website.
WordPress officially supports specific services for embedding content through oEmbed.
What are WordPress embeds?
WordPress embeds allow you to add external content to your posts and pages. You can easily embed audio files, forms, YouTube videos, Instagram posts, Twitter posts, Vimeo posts, posts from other WordPress sites, and more.
You can add content by pasting a URL into the Embed Block. If you see the message "Sorry, this content could not be embedded," it means that the URL is not supported. In this case, you'll need to use the Custom HTML Block to add the embed code, which usually includes an iframe tag.
In both cases, the content will be displayed on the website via an iframe that loads a simplified, embed-friendly version of the original page.
Why Did WordPress Introduce Embeds?
By embedding content from external sources instead of uploading large media files, users can save storage space and simplify content management. Pasting a URL showcases media from various platforms, enhancing websites' visual appeal and functionality.
What is Included in a Default Embed?
- Shows featured image if available.
The image placement depends on its size and aspect ratio. It may appear above the title or as a smaller image next to the text. - The post title appears in the embed and is clickable, directing users to the full post.
- If an excerpt is added, it will be displayed. If not, WordPress will automatically generate one using the first few words of the post.
- The site icon (favicon) and website name appear in the embed footer.
- If comments are enabled, the total number of comments will be displayed.
- A share button is included in the footer, allowing users to share the post easily.
How to Customize WordPress Embeds to Match Your Theme?
Customizing Embed Styles
WordPress comes with a default stylesheet for embedded content. To customize this, create a new CSS file in your theme's directory, named something like `embed-custom.css`.
.wp-embed-featured-image.rectangular {
margin: -25px -25px 25px;
}
p.wp-embed-heading {
margin-bottom: 10px;
}
.wp-embed-footer {
margin: 25px -25px -25px;
padding: 25px;
background: #fafafa;
}
The above code adjusts the margin for the featured image and the background color of the footer.
Next, you must ensure that your custom stylesheet loads after the default ones. To do this, enqueue it correctly in your theme's `functions.php` file with the following code:
function enqueue_embed_custom_styles() {
wp_enqueue_style( 'embed-custom', get_template_directory_uri() . '/embed-custom.css', array( 'wp-embed-template' ), null );
}
add_action( 'embed_footer', 'enqueue_embed_custom_styles' );
Set a Consistent Image Layout
You can control how images appear in embeds. By default, WordPress may display images above the title or as a small floated image next to the text. If you want all images to appear only above the title, you can enforce this with a filter.
function custom_embed_force_rectangular_image() {
return 'rectangular';
}
add_filter( 'embed_thumbnail_image_shape', 'custom_embed_force_rectangular_image' );
This code forces WordPress to always display images in a rectangular shape above the title.
Change the Site Title
By default, WordPress displays a fallback logo in case your site doesn't have one. If you wish to show only the site title, add this to your functions.php file:
function devblog_embed_only_site_title() {
return sprintf(
'<div class="wp-embed-site-title">%s</div>',
esc_html( get_bloginfo( 'name' ) )
);
}
add_filter( 'embed_site_title_html', 'devblog_embed_only_site_title' );
This ensures that only the site title appears, without any default WordPress logo.
Change the Excerpt Length for Embeds
WordPress does not have a special filter for embedding excerpts, but you can shorten them using excerpt_length with is_embed().
You can decide the amount of text you want to display and then set the excerpt accordingly.
function devblog_embed_shorter_excerpt_length( $length ) {
return is_embed() ? 25 : $length;
}
add_filter( 'excerpt_length', 'devblog_embed_shorter_excerpt_length' );
This ensures embedded excerpts are shorter without affecting the rest of your site.
Remove or modify the "Continue Reading" text
WordPress adds "Continue reading" at the end of excerpts by default. To remove it, use this line:
If you want to change it to something like "Keep exploring," use this code:
function devblog_embed_excerpt_call_to_action( $more_string ) {
if ( ! is_embed() ) {
return $more_string;
}
$processor = new WP_HTML_Tag_Processor( $more_string );
if ( $processor->next_tag( 'a' ) ) {
$processor->next_token();
$processor->set_modifiable_text( __( 'Keep exploring', 'devblog' ) );
}
return $processor->get_updated_html();
}
add_filter( 'excerpt_more', 'devblog_embed_excerpt_call_to_action', 21 );
This replaces the default text with "Keep exploring" in embedded posts.
Add Extra Content to Embeds
You can insert additional information into the embed using two hooks:
- embed_content: Adds content after the excerpt.
- embed_content_meta: Adds content in the row with comment and share icons.
Add the Published Date
To show the post’s publication date (but not for pages), use this code:
function devblog_embed_post_posted_on() {
if ( ! is_single() ) {
return;
}
$time = sprintf(
'<time datetime="%1$s">%2$s</time>',
esc_attr( get_the_date( DATE_W3C ) ),
esc_html( get_the_date() )
);
printf(
'<p class="wp-embed-posted-on">%s</p>',
sprintf(
esc_html__( 'Posted on %s', 'devblog' ),
$time
)
);
}
add_action( 'embed_content', 'devblog_embed_post_posted_on' );
Add a Like Button
If you want someone to like your post, then you can also add a like button. Use the embed_content_meta hook (This places a heart-shaped button in the embed area.)
function devblog_embed_like_button() {
if ( is_404() ) {
return;
}
?>
<div class="wp-embed-like">
<button class="wp-embed-like-button"
aria-label="<?php esc_attr_e( 'Like', 'devblog' ); ?>">
<span class="dashicons dashicons-heart"></span>
</button>
</div>
<?php
}
add_action( 'embed_content_meta', 'devblog_embed_like_button', 9 );
Style it with CSS:
.wp-embed-like {
display: inline;
margin-right: 10px;
}
.wp-embed-like-button {
margin: -8px 0 0;
padding: 0;
background: transparent;
border: none;
cursor: pointer;
outline: none;
}
.wp-embed-like-button .dashicons {
padding: 4px;
top: 8px;
}
Note: This button doesn’t store likes, but you can add functionality later.
Remove Comment and Share Buttons
WordPress automatically adds comment and share buttons to embeds. If you don’t want them, you can disable them with these simple lines:
remove_action( 'embed_content_meta', 'print_embed_comments_button' );
remove_action( 'embed_content_meta', 'print_embed_sharing_button' );
This removes the buttons, but the share dialog box (small popup visible when the user clicks on the share button) is added separately, so you’ll need to remove that too:
Where to Find Embed Template Files?
By default, WordPress doesn’t store embed templates in your theme folder. Instead, they are located in /wp-includes/theme-compat/.
Important Files
1. embed.php: The main template for all post types
2. embed-content.php: Handles embed content
3. embed-404.php: Displays when an embed isn’t available
4. header-embed.php & footer-embed.php: Manage the embed’s header and footer
To modify an embed template, copy the file you require in /wp-includes/theme-compat/ and place it within your theme directory. WordPress will use your version instead of the default.
Can You Edit Embeds with the Site Editor?
No, the WordPress Site Editor does not currently support editing embed templates. Even if your theme uses block templates, you’ll still need PHP files to customize embeds.
You can reuse embed templates across multiple websites and projects by storing them into a plugin.
wp-content/plugins/devblog-embed-template/
├─index.php
└─templates/
└── embed.php
Add the below code inside your index.php.
<?php
/**
* Plugin Name: Developer Blog Embed Template
*/
function devblog_embed_template() {
return plugin_dir_path( __FILE__ ) . 'templates/embed.php';
}
add_filter( 'embed_template', 'devblog_embed_template' );
When WordPress searches for an embed template, it follows a specific order. First, it looks in the plugin folder to see if a custom template has been defined there. If no matching file is found, WordPress then checks the active theme’s folder for an appropriate template. If neither location contains the required file, WordPress falls back to the default templates stored in the /wp-includes/theme-compat/ directory. This hierarchy ensures that custom templates take priority while still allowing WordPress to provide a fallback option when needed.
