Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 39 ยท Hooks, Templates and Settings

Template Overrides and Plugin Templates

Learn how WooCommerce finds templates, how themes override them, how wc_get_template and the locate filter work, and how to ship overridable templates in your plugin.

Every piece of storefront markup that WooCommerce prints, from the product loop to the cart table to the emails, comes from a template file. Those files can be replaced by a theme without editing the plugin, and your own extension can use the same system so that store owners can restyle what you print. This lesson explains how a template is found, how an override is made, why version numbers matter, and when a template is the wrong tool.

Hooks and templates are the two extension layers you met in The WooCommerce Hook Map. Hooks change behavior and add small pieces of output. Templates replace whole blocks of markup. Choosing between them is a real design decision, and you will see how to make it at the end. As in the rest of this track, real WooCommerce code is read-only on this page, and the runnable examples are plain-PHP stand-ins that copy the idea.

Where templates live

WooCommerce keeps its templates in the templates/ folder of the plugin. The folder mirrors the shop: cart/cart.php, checkout/form-checkout.php, single-product/price.php, emails/customer-completed-order.php, myaccount/dashboard.php and so on. A theme overrides one by copying the file to a woocommerce/ folder in the theme, keeping the same relative path:

TEXT
wp-content/plugins/woocommerce/templates/single-product/price.php   (original)
wp-content/themes/my-child-theme/woocommerce/single-product/price.php   (override)

The rule is "never edit the plugin file". An edit inside the plugin folder is lost at the next update. A copy inside the theme is not. If you build a custom theme or a child theme, that copy is the supported way to change markup. If the change is small, such as adding a line after the price, a hook is usually better, because a copy freezes the file as it was on the day you copied it.

How the search order works

WooCommerce does not include template files directly. It asks a function to find them. The two functions to remember are wc_locate_template(), which returns a file path, and wc_get_template(), which locates the file and then includes it with your variables.

PHP
<?php
// Read-only: the idea of the lookup, simplified from WooCommerce core.
function wc_locate_template( $template_name, $template_path = '', $default_path = '' ) {
    if ( ! $template_path ) {
        $template_path = WC()->template_path(); // "woocommerce/"
    }
    if ( ! $default_path ) {
        $default_path = WC()->plugin_path() . '/templates/';
    }

    // 1. Look in the child theme, then the parent theme.
    $template = locate_template( array(
        trailingslashit( $template_path ) . $template_name,
        $template_name,
    ) );

    // 2. Fall back to the plugin's own file.
    if ( ! $template ) {
        $template = $default_path . $template_name;
    }

    // 3. Let code have the last word.
    return apply_filters( 'woocommerce_locate_template', $template, $template_name, $template_path );
}

Three details are worth noting.

  1. locate_template() is a WordPress function that checks the child theme first and the parent theme second. A child theme override therefore beats a parent theme override.
  2. The second candidate in that array is the bare $template_name at the theme root. It exists for older themes and is rarely used.
  3. The woocommerce_locate_template filter runs last and receives the path that was found, the template name and the template path. A plugin can use it to redirect a template to a file of its own, which is how some extensions provide their own version of a template without asking the theme to copy anything.

A related constant, WC_TEMPLATE_DEBUG_MODE, tells the lookup to ignore theme overrides. It is a debugging aid for finding out whether a layout problem comes from a stale override. Do not leave it on in production.

flowchart TD
    A["wc_get_template('cart/cart.php')"] --> B["Child theme: woocommerce/cart/cart.php?"]
    B -- found --> Z["Include this file"]
    B -- no --> C["Parent theme: woocommerce/cart/cart.php?"]
    C -- found --> Z
    C -- no --> D["Plugin: templates/cart/cart.php"]
    D --> E["Filter: woocommerce_locate_template"]
    Z --> E
    E --> F["Include the final path"]

The lookup order: child theme, parent theme, plugin, then the locate filter has the last say.

Using wc_get_template

wc_get_template() takes the template name and an array of arguments. It extracts the arguments into local variables, so the template file sees them as plain variables. It also fires actions before and after, which gives other code a chance to wrap your output.

PHP
<?php
// Read-only: printing one of your own templates.
wc_get_template(
    'notice-box.php',
    array(
        'heading' => __( 'Free shipping', 'acme-notice' ),
        'message' => $message,
    ),
    'acme-notice/',                                  // folder in the THEME to look in
    plugin_dir_path( __FILE__ ) . 'templates/'       // folder in YOUR plugin as fallback
);

The third argument is the theme-side folder. The default is woocommerce/, but a plugin that ships its own templates should pass its own folder, such as acme-notice/, so that overrides for different plugins do not collide. The fourth argument is the absolute path to your plugin's templates/ folder, which is the fallback when the theme has no override.

wc_get_template_html() has the same signature and returns the markup as a string instead of printing it. Use it when you need to put the result in an AJAX response, an email body or a block render callback.

The template file itself is an ordinary PHP file that prints markup using the extracted variables. Inside it you must escape output, because a theme author or a user may influence the values:

PHP
<?php
/**
 * Notice box.
 *
 * This template can be overridden by copying it to yourtheme/acme-notice/notice-box.php.
 *
 * @package Acme_Notice\Templates
 * @version 1.2.0
 */

defined( 'ABSPATH' ) || exit;
?>
<div class="acme-notice-box">
    <strong><?php echo esc_html( $heading ); ?></strong>
    <p><?php echo wp_kses_post( $message ); ?></p>
</div>

Two habits matter here: the defined( 'ABSPATH' ) || exit; guard stops direct access to the file, and the DocBlock tells the store owner both where to copy the file and which version it is.

Template versions and the outdated notice

The @version line in a WooCommerce template's DocBlock is not decoration. WooCommerce compares the version of an override in the theme with the version of the plugin's original file. When the original has a higher version, the System Status report marks the override as outdated, and the admin may show a notice. The point is simple: if the plugin changed the markup, hooks or variables of a template, a stale copy in the theme may stop working or miss a security fix.

As an extension author, you follow the same rule. Bump the @version of one of your templates only when you change something a copy would need: renamed variables, a new required variable, changed markup that styles depend on. Do not bump it for a typo fix in a comment. Mention template changes in your changelog, so store owners know when to compare their copies.

As a store owner or theme developer, the sensible habit is to copy as little as possible. Each copy is a maintenance debt. Prefer hooks, CSS and filters, and copy a template only when markup has to change.

Template parts

Some templates are not loaded with wc_get_template(). The product loop item is loaded with wc_get_template_part( 'content', 'product' ), which looks for content-product.php (and content.php as a fallback) following the same theme-then-plugin order. Template parts are the older style, kept so that themes written years ago keep working. In new code, prefer wc_get_template() with explicit arguments, because passing variables explicitly is easier to read and to test than relying on globals such as $product.

Try it: a template locator

This stand-in has the same three steps as the real function. A small array pretends to be the file system, so the output is the same every time. Try adding a parent-theme file or changing which file exists, and see which one wins.

PHP Child theme, parent theme, plugin, filter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The real files, the real locate_template() and the real filter belong to WordPress and WooCommerce. What is simulated here is only the order of the search, which is the part you need to reason about when an override seems to be ignored.

Try it: render, escape, and find outdated overrides

The second example covers the other two ideas from this lesson: arguments become variables and values get escaped, and a version comparison tells you which overrides are outdated.

PHP Render with arguments and check versions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The renderer uses eval only because a TryIt is a single file. Real WordPress never evaluates strings; it includes a file with include. What carries over is the shape: variables in, escaped markup out, and a version check you can run over a folder of overrides.

Hooks or templates?

A short checklist helps you choose.

  • Add a small piece of output (a badge, a notice, a line under the price): use a hook. It survives theme changes.
  • Change a value (a price format, a label, a CSS class list): use a filter.
  • Rearrange or remove existing blocks: remove and re-add callbacks with different priorities, as in the hook map lesson.
  • Change the structure of a block (a different table layout in the cart): a template override is the right tool, but copy only the file you need and keep track of its version.
  • Ship markup in your own plugin: put it in a template loaded with wc_get_template() and a plugin-specific theme folder, so a store owner can restyle it.

The block-based cart and checkout do not use the classic cart and checkout templates at all, so overrides of those files have no effect there. That is one reason template copies age badly. See Cart and Checkout Blocks Extensibility for the replacement extension points.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A child theme and its parent theme both contain woocommerce/cart/cart.php. Which file is used?

    locate_template() checks the child theme first and the parent second, so the child theme copy wins.
  2. 2. Why should a plugin pass its own folder name as the third argument of wc_get_template()?

    The default theme folder is woocommerce/. A plugin-specific folder such as acme-notice/ keeps its overrides separate from WooCommerce's and from other extensions'.
  3. 3. The System Status report marks a theme override as outdated. What does that mean?

    WooCommerce compares the @version line in the DocBlock of the copy with the original. If the original is newer, the copy may be missing markup or fixes.
  4. 4. You only want to show a short line under the product price. What is usually the best approach?

    A hook adds output without freezing a copy of a template. Copying templates is for structural changes.

Summary

  • Storefront markup comes from template files that a theme can override by copying them into a woocommerce/ folder, child theme first, then parent theme, then the plugin.
  • wc_locate_template() finds the file, wc_get_template() includes it with extracted arguments, and wc_get_template_html() returns the markup as a string.
  • The woocommerce_locate_template filter lets code redirect a template to another file after the normal search.
  • The @version line drives the outdated-override report; bump it in your own templates only when a copy would need an update.
  • Ship your plugin templates with wc_get_template(), your own theme folder, an escaping habit and an ABSPATH guard.
  • Prefer hooks and filters for small changes; copy a template only for structural ones.

Next: Adding Settings Pages and Tabs