Template Overrides

TemplateX compiles WooCommerce override source files into the same native override paths WooCommerce expects in a theme.

Choose The Right Tool#

Use normal TemplateX views for most pages:

Use WooCommerce overrides when WooCommerce expects a specific template file:

During publishing, TemplateX writes those files into the compiled theme's native woocommerce/ override folder.

Smallest Override#

Create a source override:

<h1 class="product-title">{{ title }}</h1>

TemplateX compiles it to a native WooCommerce override path:

The compiled output is normal PHP. It does not need the TemplateX plugin at runtime.

Single Product Override#

You can replace the main single product override:

<main class="product-page">  {{ notices }}  <section class="product-page__media">    {{ product:image class="product-image" size="large" }}    {{ gallery_images }}      <img src="{{ url }}" alt="{{ alt }}">    {{ /gallery_images }}  </section>  <section class="product-page__summary">    <h1>{{ title }}</h1>    <div>{{ price_html }}</div>    <div>{{ short_description }}</div>    {{ cart:add }}      <button type="submit">Add to cart</button>    {{ /cart:add }}  </section></main>

WooCommerce product values are available because woocommerce/single-product.php is a product-aware path.

For a normal theme single product page, prefer resources/views/single-product.php. See Single Product Page.

Product Category Templates#

Product categories use WordPress taxonomy template names, not page or post-category template names:

The product_cat part is required because WooCommerce product categories are a WordPress taxonomy named product_cat. WordPress will not load page-dames.php for a product category archive, and category-dames.php only targets the built-in blog post category taxonomy.

Use these files by scope:

Inside product category templates, {{ query:product }} and {{ query:products }} automatically inherit the current product category unless you provide your own taxonomy:product_cat filter.

<section>  <h1>{{ category_name }}</h1>  {{ query:products limit="12" }}    <article>      <a href="{{ url }}">        <img src="{{ featured }}" alt="">        <h2>{{ title }}</h2>      </a>      <div>{{ price_html }}</div>    </article>  {{ /query:products }}</section>

Use {{ category_name }} outside the product loop if you want to print the current product category name. Keep {{ title }} inside the product loop for the product title.

Email Template Overrides#

WooCommerce HTML email templates also use the native override tree:

Email templates are usually written with native PHP variables that WooCommerce passes into the email template, such as $order, $email_heading, and $email. See Customize Mail With HTML Templates.

Override A Small Template Part First#

Prefer small overrides before replacing large WooCommerce templates:

<div class="product-price">  {{ price_html }}</div>

Small overrides are easier to maintain when WooCommerce updates its own templates.

Keep Overrides Upgrade-Friendly#

WooCommerce's normal override model expects the same subdirectory structure as WooCommerce's templates directory. Keep that shape under resources/views/woocommerce/.

Good:

Risky:

If WooCommerce does not know the path, it will not load the override as a WooCommerce template.

Use Page Templates For Page Layout#

Do not use a WooCommerce override when a normal page wrapper is enough:

<main class="checkout-page">  <h1>Checkout</h1>  {{ notices }}  {{ checkout }}</main>

This keeps checkout behavior native and avoids replacing WooCommerce internals. See Checkout Page.

When Overrides Are Worth It#

Use WooCommerce overrides when:

• A WooCommerce template part outputs markup you need to replace.
• A product extension requires a WooCommerce template file.
• You need to preserve WooCommerce hooks or template loading behavior.
• The change belongs to a WooCommerce-owned template, not just the page wrapper.

Use normal TemplateX views when:

• You are building a product section on a landing page.
• You are designing a cart or checkout page around the native tags.
• You only need headings, wrappers, spacing, or layout around WooCommerce output.

Maintenance Habit#

When WooCommerce updates a template you override, compare your source override with the new WooCommerce template. Keep only the intentional theme changes in your TemplateX source.