Block Theme Development

Block themes leverage WordPress Full Site Editing (FSE) to provide visual, no-code customization experiences. WooCommerce fully supports block themes with specialized templates, blocks, and global styling through theme.json.

This guide covers block themes using HTML templates and FSE. For classic PHP-based theme development, see Classic Theme Development.

New to block theme development? Complete the WordPress Block Theme Development Course before diving into WooCommerce-specific concepts.

Block Theme Fundamentals

Block themes use HTML files instead of PHP templates and are styled through theme.json rather than traditional CSS. This architecture enables:

Visual editing - Users customize templates in the Site Editor
Global styles - Consistent styling via theme.json configuration
Better performance - Only required CSS loads on each page
User control - Non-developers can modify layouts without code

Prerequisites

Before developing WooCommerce block themes, ensure you understand:

WordPress block editor (Gutenberg)
Block templates and template parts
theme.json configuration
Global styles and settings
Site Editor interface

WooCommerce Block Templates

WooCommerce provides default block templates for product and shop pages. These templates are located in:

wp-content/plugins/woocommerce/templates/templates/blockified/

Available Templates

Product Templates
Taxonomy Templates
Page Templates

single-product.html - Single product page layout
archive-product.html - Main shop/product catalog
product-search-results.html - Product search results

taxonomy-product_cat.html - Products by category
taxonomy-product_tag.html - Products by tag
taxonomy-product_attribute.html - Products by attribute

page-cart.html - Shopping cart page
page-checkout.html - Checkout page
page-coming-soon.html - Coming soon page
order-confirmation.html - Order confirmation

Template Hierarchy

WooCommerce block templates follow WordPress template hierarchy with specific fallback patterns:

Single Product:
single-product-{slug}.html  →  single-product.html  →  single.html

Category Archive:
taxonomy-product_cat-{slug}.html  →  taxonomy-product_cat.html  →  archive-product.html

Tag Archive:
taxonomy-product_tag-{slug}.html  →  taxonomy-product_tag.html  →  archive-product.html

Attribute Archive:
taxonomy-product_attribute-{slug}.html  →  taxonomy-product_attribute.html  →  archive-product.html

Category, tag, and attribute templates fall back to archive-product.html if specific taxonomy templates aren’t provided.

Overriding Block Templates

Create custom templates by adding HTML files to your theme’s /templates/ directory:

Create Templates Directory

Ensure your theme has a templates/ folder:

wp-content/themes/yourtheme/templates/

Copy WooCommerce Template

Copy the template you want to customize from WooCommerce to your theme:

FROM: wp-content/plugins/woocommerce/templates/templates/blockified/single-product.html
TO:   wp-content/themes/yourtheme/templates/single-product.html

Edit in Site Editor

Customize the template using the WordPress Site Editor:Appearance → Editor → Templates → Single Product

Export Changes (Optional)

Export modified templates to commit them to your theme repository.

Example: Custom Single Product Template

<!-- wp:template-part {"slug":"header","theme":"yourtheme","tagName":"header"} /-->

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
    
    <!-- wp:woocommerce/breadcrumbs /-->
    
    <!-- wp:woocommerce/store-notices /-->
    
    <!-- wp:columns -->
    <div class="wp-block-columns">
        
        <!-- wp:column {"width":"50%"} -->
        <div class="wp-block-column" style="flex-basis:50%">
            <!-- wp:woocommerce/product-image-gallery /-->
        </div>
        <!-- /wp:column -->
        
        <!-- wp:column {"width":"50%"} -->
        <div class="wp-block-column" style="flex-basis:50%">
            
            <!-- wp:post-title {"level":1} /-->
            
            <!-- wp:woocommerce/product-rating /-->
            
            <!-- wp:woocommerce/product-price {"fontSize":"large"} /-->
            
            <!-- wp:post-excerpt /-->
            
            <!-- wp:woocommerce/add-to-cart-form /-->
            
            <!-- wp:woocommerce/product-meta /-->
            
        </div>
        <!-- /wp:column -->
        
    </div>
    <!-- /wp:columns -->
    
    <!-- wp:woocommerce/product-details /-->
    
    <!-- wp:woocommerce/related-products /-->
    
</div>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","theme":"yourtheme","tagName":"footer"} /-->

Specific Product Templates

Create templates for specific products using their slug:

<!-- single-product-leather-jacket.html -->
<!-- Only applies to product with slug "leather-jacket" -->

<!-- wp:template-part {"slug":"header"} /-->

<div class="luxury-product-layout">
    <!-- Custom layout for premium products -->
    <!-- wp:woocommerce/product-image-gallery {"thumbnailsPosition":"left"} /-->
    <!-- wp:woocommerce/product-price {"fontSize":"x-large"} /-->
</div>

<!-- wp:template-part {"slug":"footer"} /-->

Block Template Parts

WooCommerce provides specialized template parts for reusable components:

Available Template Parts

mini-cart.html - Used inside the Mini-Cart block drawer
checkout-header.html - Header used in checkout template

Override template parts in your theme’s /parts/ directory:

wp-content/themes/yourtheme/parts/
├── mini-cart.html
└── checkout-header.html

Example: Custom Mini-Cart Template Part

<!-- parts/mini-cart.html -->

<!-- wp:woocommerce/filled-mini-cart-contents-block -->
<div class="wp-block-woocommerce-filled-mini-cart-contents-block">
    
    <!-- wp:woocommerce/mini-cart-title-block /-->
    
    <!-- wp:woocommerce/mini-cart-items-block /-->
    
    <!-- wp:woocommerce/mini-cart-footer-block -->
    <div class="wp-block-woocommerce-mini-cart-footer-block">
        
        <!-- wp:woocommerce/mini-cart-cart-button-block /-->
        
        <!-- wp:woocommerce/mini-cart-checkout-button-block /-->
        
        <!-- Custom message -->
        <!-- wp:paragraph {"fontSize":"small"} -->
        <p class="has-small-font-size">Free shipping on orders over $50!</p>
        <!-- /wp:paragraph -->
        
    </div>
    <!-- /wp:woocommerce/mini-cart-footer-block -->
    
</div>
<!-- /wp:woocommerce/filled-mini-cart-contents-block -->

<!-- wp:woocommerce/empty-mini-cart-contents-block -->
<div class="wp-block-woocommerce-empty-mini-cart-contents-block">
    <!-- wp:paragraph -->
    <p>Your cart is empty</p>
    <!-- /wp:paragraph -->
</div>
<!-- /wp:woocommerce/empty-mini-cart-contents-block -->

Styling with theme.json

Global styles in theme.json provide the primary styling mechanism for block themes. WooCommerce blocks support all standard theme.json style properties.

Basic WooCommerce Block Styling

{
  "version": 2,
  "styles": {
    "blocks": {
      "woocommerce/product-price": {
        "color": {
          "background": "#f0f0f0",
          "text": "#333333"
        },
        "typography": {
          "fontSize": "1.5rem",
          "fontWeight": "700",
          "fontStyle": "normal"
        },
        "spacing": {
          "padding": {
            "top": "0.5rem",
            "bottom": "0.5rem"
          }
        }
      },
      "woocommerce/product-button": {
        "color": {
          "background": "#2c3e50",
          "text": "#ffffff"
        },
        "border": {
          "radius": "4px"
        },
        "spacing": {
          "padding": "1rem 2rem"
        }
      },
      "woocommerce/product-image": {
        "border": {
          "radius": "8px"
        }
      }
    }
  }
}

Complete WooCommerce Styling Example

{
  "styles": {
    "blocks": {
      "woocommerce/product-price": {
        "color": {
          "text": "#e63946"
        },
        "typography": {
          "fontSize": "1.75rem",
          "fontWeight": "700",
          "lineHeight": "1.2"
        }
      },
      "woocommerce/product-rating": {
        "color": {
          "text": "#f4a261"
        },
        "spacing": {
          "margin": {
            "bottom": "1rem"
          }
        }
      },
      "woocommerce/add-to-cart-form": {
        "spacing": {
          "margin": {
            "top": "2rem",
            "bottom": "2rem"
          }
        }
      }
    }
  }
}

Advantages of theme.json Styling

Performance

Only necessary CSS loads per page, reducing bundle size and improving load times

User Customization

Users can modify styles through the Site Editor without touching code

Conflict Management

Gracefully handles conflicts between plugins and themes

Markup Independence

Styles persist even when block markup or class names change

Avoid writing CSS that depends on specific block nesting or HTML structure. Users can freely rearrange blocks, breaking CSS selectors that rely on hierarchy.

WooCommerce Block Reference

Common WooCommerce blocks available in block templates:

Product Display Blocks

Block	Purpose
`woocommerce/product-image-gallery`	Product images with thumbnails
`woocommerce/product-price`	Product price display
`woocommerce/product-rating`	Star rating display
`woocommerce/product-meta`	SKU, categories, tags
`woocommerce/add-to-cart-form`	Add to cart functionality
`woocommerce/product-details`	Product tabs (description, reviews)
`woocommerce/breadcrumbs`	Breadcrumb navigation

Product Collection Blocks

Block	Purpose
`woocommerce/product-collection`	Query and display products
`woocommerce/product-template`	Layout for individual products
`woocommerce/related-products`	Related products display
`woocommerce/handpicked-products`	Manually selected products

Cart & Checkout Blocks

Block	Purpose
`woocommerce/cart`	Complete cart block
`woocommerce/checkout`	Complete checkout block
`woocommerce/mini-cart`	Mini cart drawer
`woocommerce/cart-items-block`	Cart line items
`woocommerce/checkout-fields-block`	Checkout form fields

Utility Blocks

Block	Purpose
`woocommerce/store-notices`	Display WooCommerce notices
`woocommerce/customer-account`	Account link/menu
`woocommerce/catalog-sorting`	Product sorting options
`woocommerce/product-results-count`	Result count display

For the complete block reference including all attributes and settings, see the WooCommerce Block Reference.

CSS Styling (When Necessary)

While theme.json is preferred, some styling requires custom CSS. When writing CSS for block themes:

WooCommerce strongly discourages CSS selectors that rely on specific block nesting. Users can rearrange blocks freely, breaking hierarchy-dependent selectors.

CSS Best Practices

/* ✓ GOOD - Targets block directly */
.wp-block-woocommerce-product-price {
    font-size: 1.5rem;
    color: #e63946;
}

/* ✓ GOOD - Uses component classes */
.wc-block-components-product-price {
    font-weight: 700;
}

/* ✗ AVOID - Relies on nesting */
.wp-block-woocommerce-product-collection 
  .wp-block-woocommerce-product-price {
    color: red; /* Breaks if user moves price block */
}

/* ✗ AVOID - Depends on structure */
.wc-block-checkout .wc-block-components-totals-item:first-child {
    /* Breaks if user reorders blocks */
}

Block and Component Class Names

WooCommerce uses BEM naming with two prefixes:

.wc-block- - Block-specific classes
.wc-block-components- - Reusable component classes

Target components globally or within specific blocks:

/* Style all prices globally */
.wc-block-components-formatted-money-amount {
    font-style: italic;
}

/* Style prices only in checkout */
.wc-block-checkout .wc-block-components-formatted-money-amount {
    font-style: italic;
}

Container Queries for Cart/Checkout

Cart and Checkout blocks define CSS containers for responsive styling:

.wp-block-woocommerce-checkout {
    container-type: inline-size;
}

/* Use container queries instead of media queries */
@container (min-width: 700px) {
    .wc-block-checkout__sidebar {
        padding: 2rem;
    }
}

@container (max-width: 520px) {
    .wc-block-checkout__form {
        padding: 1rem;
    }
}

Container queries allow responsive design based on parent container width, not viewport width. This provides better adaptability in varied layouts.

User Customization Considerations

Block themes empower users to customize templates through the Site Editor. Design themes with this in mind:

Provide Sensible Defaults

Set up well-structured default templates that work out-of-the-box but remain customizable.

Use Global Styles Extensively

Define comprehensive theme.json styles so users can modify appearance without CSS.

Document Customization Options

Provide theme documentation explaining which blocks and styles users can safely modify.

Test User Modifications

Test templates with various block arrangements to ensure CSS doesn’t break with user changes.

Users can modify templates via the Site Editor. Always keep in mind that blocks may be moved, removed, or added in unexpected ways.

Migration from Classic Themes

Converting classic themes to block themes requires restructuring templates and styles:

Template Conversion
Style Migration
Hook Alternatives

Convert PHP templates to HTML block templates:Classic (PHP):

<?php get_header(); ?>
<div class="container">
    <?php woocommerce_content(); ?>
</div>
<?php get_footer(); ?>

Block (HTML):

<!-- wp:template-part {"slug":"header"} /-->
<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
    <!-- WooCommerce blocks here -->
</div>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer"} /-->

Move CSS to theme.json where possible:Classic (CSS):

.woocommerce .product-price {
    font-size: 1.5rem;
    color: #e63946;
}

Block (theme.json):

{
  "styles": {
    "blocks": {
      "woocommerce/product-price": {
        "typography": {"fontSize": "1.5rem"},
        "color": {"text": "#e63946"}
      }
    }
  }
}

Replace PHP hooks with block patterns or template customization:Classic (Hook):

add_action('woocommerce_single_product_summary', 'custom_badge', 6);

Block (Template):

<!-- Add directly in template -->
<!-- wp:paragraph {"className":"custom-badge"} -->
<p class="custom-badge">Featured!</p>
<!-- /wp:paragraph -->

Best Practices

Prioritize theme.json

Use global styles for all styling that doesn’t require complex selectors

Avoid Structure Dependency

Never write CSS that assumes specific block nesting or order

Test with Variations

Test templates with blocks added, removed, and rearranged by users

Document User Options

Clearly explain which customizations users can make safely

Next Steps

Block Reference

Complete reference for all WooCommerce blocks

Theme Customization

Advanced styling and customization techniques

Create Block Theme Plugin

Tool for creating and exporting block themes

Getting Started

Core Concepts

Extension Development

Theme Development

Block Development

Features

​Block Theme Development

​Block Theme Fundamentals

​Prerequisites

​WooCommerce Block Templates

​Available Templates

​Template Hierarchy

​Overriding Block Templates

​Example: Custom Single Product Template

​Specific Product Templates

​Block Template Parts

​Available Template Parts

​Example: Custom Mini-Cart Template Part

​Styling with theme.json

​Basic WooCommerce Block Styling

​Complete WooCommerce Styling Example

​Advantages of theme.json Styling

Performance

User Customization

Conflict Management

Markup Independence

​WooCommerce Block Reference

​Product Display Blocks

​Product Collection Blocks

​Cart & Checkout Blocks

​Utility Blocks

​CSS Styling (When Necessary)

​CSS Best Practices

​Block and Component Class Names

​Container Queries for Cart/Checkout

​User Customization Considerations

​Migration from Classic Themes

​Best Practices

Prioritize theme.json

Avoid Structure Dependency

Test with Variations

Document User Options

​Next Steps

Block Reference

Theme Customization

Create Block Theme Plugin

Build docs developers (and LLMs) love

Block Theme Development

Block Theme Fundamentals

Prerequisites

WooCommerce Block Templates

Available Templates

Template Hierarchy

Overriding Block Templates

Example: Custom Single Product Template

Specific Product Templates

Block Template Parts

Available Template Parts

Example: Custom Mini-Cart Template Part

Styling with theme.json

Basic WooCommerce Block Styling

Complete WooCommerce Styling Example

Advantages of theme.json Styling

WooCommerce Block Reference

Product Display Blocks

Product Collection Blocks

Cart & Checkout Blocks

Utility Blocks

CSS Styling (When Necessary)

CSS Best Practices

Block and Component Class Names

Container Queries for Cart/Checkout

User Customization Considerations

Migration from Classic Themes

Best Practices

Next Steps