Skip to Content
Add a Theme image to A Block Theme

Add a Theme image to A Block Theme

Creating a WordPress Block theme? Want to learn how to add a theme image to a block theme? Looking to include your unique branding into your custom theme? Well look no further this post is for you!

Block Theme Template’s and Template Parts

Before you add an image to your block theme template, you might want to learn how to create block theme templates first. Check out the WordPress documentation here. It’s pretty simple to get started, so don’t over think it.

Just add a folder to your root theme folder called /templates and then insert whichever templates you want to include, for example index.html, 404.html and so on.

Your file structure could look like this:



The easiest way to build block theme templates is to start with a blank index.html file in the templates folder. Next, in the site editor, add the blocks you want to the index.html visually. From there you can navigate to the sidebar on the right side of the Site Editor. Select the 3 vertical dots in the top menu and then ‘Code Editor’ under the Editor menu.

Copy the html comment code from the Site Editor and paste it into your index.html file. Repeat for each template you want to create.

Want to learn how to hide a block from a template or template part? Check out our post on the subject here.

Template Parts

Creating a template part is nearly identical to creating a template. The only difference is that you’ll create a separate folder titled ‘parts’ in your root theme folder. Within the parts folder is where you will have your template parts, for instance a header.html

Your file path for your template parts would look like this:


Add Theme Image to Block Theme Templates and Template Parts

First start by adding a blank image block to your template and adjust the image block settings however you want.

Next, you’ll need to upload your branding image into a folder in your theme files. You could create a folder called ‘assets’ in your root theme folder.

The file path would look like this:


Paste the block html from the Site Editor into your template-name.html file. (Note: that the blank image block has an img html tag with no src attribute.) To add a theme image to a block theme template or template part, in your code editor start by adding a src attribute to the image block. Your image tag will look something like this:

<img src="" alt="" />

Next, add the image file location to the src attribute of the image.

The image file path should be relative, not absolute, so that the image will load in any environment. The trick is to realize that the src must be relative to the root WordPress folder. For WordPress site’s that’s usually called the ‘public’ folder.

Let’s say you have an assets folder in your theme’s root folder and within that assets folder is your image.

Your image src would look like this:

<img src="/wp-content/themes/my-theme/assets/image-title.png" />

The image block within the template-name.html file could look like this:

<!-- wp:image {"width":160,"height":160,"style":{"layout":{"selfStretch":"fixed","flexSize":"160px"}}} -->
<figure class="wp-block-image is-resized"><img src="/wp-content/themes/my-theme/assets/image-title.png" alt="" width="160" height="160"/></figure>
<!-- /wp:image -->

Like developing with WordPress? Check out this fun article that walks you through incorporating WordPress components in a React project from scratch.

Block Patterns

Before you get started adding images to your block pattern, you might want to learn how to include Block Patterns in your theme. To do that you’ll want to use the register_block_pattern() php function in your theme or plugin function file. Check out the documentation here for more on how to use this function.

The register_block_pattern() function looks like this:

function theme_slug_block_pattern() {
        'title'       => __( 'An Image', 'theme-slug' ),
        'description' => _x( 'An image block pattern for some reason', 'theme-slug' ),
        'categories'  => array( 'theme-slug-custom-category' ),
        'content'     => "<!-- wp:image {"width":160,"height":160,"style":{"layout":{"selfStretch":"fixed","flexSize":"160px"}}} -->
<figure class="wp-block-image is-resized"><img alt="" width="160" height="160"/></figure>
<!-- /wp:image -->",

The register_block_pattern function can be called on the init action like this below:

add_action( 'init', 'theme_slug_block_pattern' );

Keep in mind that the content attribute of the register_block_pattern function is where you will paste the pattern you’ve created. This can be done in the visual editor and copy/pasted using the ‘Code Editor’ setting in the Editor sidebar menu. Think of the content attribute of the register_block_pattern as a mini template or template part.

Images can sometimes cause LCP scores to go down. Learn some tips on how to improve LCP without a developer here.

Add image to Block Theme Pattern

To add an image to the block pattern, you can use php functions in the src attribute of the image block. The second parameter of the register_block_pattern is an array. Within that array is the content where the block pattern content actually lives.

To add a theme image to the block pattern dynamically, you can simply use the esc_url( get_template_directory_uri() ) function within the image src attribute like this:

'content'     => "<!-- wp:image {"width":160,"height":160,"style":{"layout":{"selfStretch":"fixed","flexSize":"160px"}}} -->
<figure class="wp-block-image is-resized"><img src="' . esc_url( get_template_directory_uri() ) . '/assets/images/placeholder.png" alt="" width="160" height="160"/></figure>
<!-- /wp:image -->",

Want to learn how to use Array methods in React? Check out this fun and informative article on just that!


That’s it! Hopefully now you know how to add theme branding images to your Block theme templates, template parts, and patterns.

Photo by Markus Winkler on Unsplash