Overriding the WooCommerce template files: Step by step guide

Today we look into how to customize the WooCommerce template files, in particular, we focus on how to create your template files and use the folder structure for easy WooCommerce theme customization.

In this tutorial, we’ll go trough how to create your own home, products, categories, shop, cart, checkout, and emails page templates. By the end of this tutorial, you should be able to create your own WooCommerce custom templates for your WooCommerce store. All changes can be done your child WooCommerce theme, thus you won’t lose your customization in future updates.

We walk through all steps, from the most basic elements, organization, and hands-on examples.

Let’s get started!

The basic structure of a child theme and WooCommerce template files

The first step of our customization process is creating a WordPress child theme. There are many good guides online, the official WordPress guide includes very detailed instructions. In its most basic version, a WordPress child theme usually contains just the style.css and functions.php files:

 

The first step of our customization process is creating a WordPress child theme. There are many good guides online, the official WordPress guide includes very detailed instructions. In its most basic version, a WordPress child theme usually contains just the style.css and functions.php files:

As you may know, a child theme works by a system of standardized file paths and names. Therefore, in order to add your own custom files you just need to use the right filename in the right folder. Thus, if you have a page.php file in your child theme, WordPress loads it instead of the parent theme’s file. If you don’t have a file, WordPress loads the parent WordPress theme files.

The custom WooCommerce template works the same way. You just need to have your files in the right folders to load them instead of the main WooCommerce files. The main difference is that all WooCommerce files are inside the /woocommerce folder of your WooCommerce theme.

For example, if you add a file named single-product.php in the woocommerce folder of your WooCommerce theme (for example WooCommerce storefront), it replaces the original file. Thus, WooCommerce reads your single-product.php instead of its default file when it is loading that element.

This is a great step towards an upgrade-safe development. This means that you can customize all the WooCommerce templates without touching the plugin files. Hence, all your custom code is safe in your own WordPress theme or child theme folder.

You may be wondering how does WooCommerce even know that I have custom template files? For example, I could be simply using a folder named WooCommerce for another reason entirely. There is a simple trick though, your theme needs to declare WooCommerce support. You can do that with this code snippet:

function mytheme_add_woocommerce_support() {
  add_theme_support( 'woocommerce' );
}
add_action( 'after_setup_theme', 'mytheme_add_woocommerce_support' );

Once this is present, WooCommerce searches for a woocommerce folder in your WordPress theme or child theme. When WooCommerce finds that folder, it tries to load files from it, instead of their own. A quick way to get familiarized with all possible files and folders is to check WooCommerce’s template structure. You can find it under /wp-content/plugins/woocommerce/templates.

The only exception for a theme file that is loaded outside the /woocommerce folder is the woocommerce.php file. Which is a file you add in your theme’s root folder for older WooCommerce versions for a quick WooCommerce fix. It is intended to adjust display issues in case you are running WooCommerce older than 3.3. If you aren’t, you don’t need to use it and you can rely only on the regular WooCommerce template files.

Now let’s get started with some edits.

Your WooCommerce Main Store and Product Archives

The first step is to make sure you are running an updated WooCommerce version. Generally, anything newer than 3.3.x should be fine. This is to make sure that you don’t have (or don’t need) the woocommerce.php file in your theme’s root folder. This file overwrites the woocommerce/archive-product.php file, thus keep that in mind in case you absolutely need it.

Then make sure you have declared WooCommerce support in your theme or child theme as explained above. Once that is set, we can create our /woocommerce folder and add our files there.

To make things easier, copy the files from /wp-content/plugins/woocommerce/templates into wp-content/themes/mytheme/woocommerce. But you should really just copy the files you need. Otherwise, if you add unnecessary files, you lose track of your customizations. In addition, you lose any new styling WooCommerce may bring in their own files, as you are overwriting them.

This is the main structure of our child theme now, with our little /woocommerce addition.

And this is our copy of the WooCommerce templates that we edit in this tutorial:

Then it’s a matter of editing the files we want to customize. For the main store and product archive layout, we use the /woocommerce/archive-product.php. Due to how well coded these files are, often it’s easy to understand what is going on.

For example, the archive-product.php file is a main WooCommerce template file. This means that this file loads other files inside of it. Thus, if you need a header, you need to call it. If you need a loop, you need to call it.

On the other hand, you can use some other custom template files for smaller elements of your product page layout. For example, the /woocommerce/global/breadcrumb.php is a helpful file, and a lot of other files load it. Whenever you see a breadcrumb feature, it is there.

Back to our archive-product.php, there you can change anything you want. For example, let’s add a custom message before our products list. You just need to add this code before the line 33:

<h1>This is just my shop</h1>
<p>Thanks for stopping by!</p>

This can be used for adding custom headers, removing the sidebar, changing classes and other theme options.

The Single Product WooCommerce Template

You can edit the single product page view in the single-product.php file. Thus, we can apply a very similar edit by adding your own code snippets. For example, on line 33 you could add this one:

<h1>This is an amazing hand-crafted product</h1>
<p>Check out related products, or read more about our values</p>

It is worth noticing that other WordPress and WooCommerce functions still work in these pages. Thus, you can add custom messages depending on the product ID, category and other aspects. Furthermore, all user-related functions work as well. Therefore, you can customize the product display depending on the current user, user roles, past orders. For example, you could show a message if that user has bought that product or a similar one from the same product category before. Or even if they have visited similar products from your online store.

Another interesting customization idea is using the child theme itself. Although you are using the custom WooCommerce template, you can copy the single-product.php file in the root folder of your child theme. Then, you can use the WordPress template hierarchy naming for completely custom files. For example, if you rename that file to single-product-{$slug}.php that file is loaded just for the product with that particular slug. Hence, the single-product-flying-ninja.php file is loaded just for the site.com/product/flying-ninja.

Custom WooCommerce Cart Template

The WooCommerce cart has a folder for itself. And that’s for a good reason.

There are many variations for the cart states and elements, and you can customize each of them using these files. The main file is /woocommerce/cart/cart.php. You can edit the line 21 and add this for a message to your customers when they reach the cart:

<h1>Welcome to our store!</h1>
<p>If you have any questions, feel free to ask!</p>

There are many other files you can use for your edits, here is a summary of them:

• cart-empty.php
• cart-item-data.php
• cart-shipping.php
• cart-totals.php
• cart.php
• cross-sells.php
• mini-cart.php
• proceed-to-checkout-button.php
• shipping-calculator.php

For example, if you want to change the markup for the cart widget, you could use the woocommerce/cart/mini-cart.php file.

WooCommerce Templates for the Checkout Workflow

One of the most important elements of your online shop is the checkout feature. Thus, you may want to ensure that the checkout experience is as smooth and as clear as possible. Therefore, a custom markup for that section can provide you custom elements or additional coding opportunity.

The checkout files are under /woocommerce/checkout. As you can see, there are many files for this section. WooCommerce calls each template in each step. For instance, form-shipping.php is called when you are adding the shipping details.

Don’t forget that if you want to add new fields to these elements you need to change the backend code as well. You can read more about this in our article on “How to create WooCommerce customer registration with custom fields“.

Maybe you want custom widgets, JS or WordPress plugins to format your fields. Often these plugins just require you to add a custom ID or CSS class to target them. Then you can open one of the cart files, form-shipping.php, for example. Then edit it to include your desired class or ID. For instance, edit line 21 to be:

<div class="woocommerce-billing-fields" id="custom-fields">

Conclusion

Today we looked into how to create custom WooCommerce template files. We investigated how the WooCommerce templating works, and how to incorporate that into your WordPress child theme. In addition, we dived into how to customize different elements of your WooCommerce online store.

We hope you enjoyed and see you again next time!