Theming for Woo blocks

Note: We're assuming you have some previous knowledge about block theme development and some WordPress concepts. If you are completely new to block theme development, please check Develop Your First Low-Code Block Theme to learn about block theme development, and explore the Create Block Theme plugin tool when you're ready to create a new theme.

General concepts

Block templates

WooCommerce comes with several block templates by default. Those are:

• Single Product (single-product.html)
• Product Catalog (archive-product.html)
  • Products by Category (taxonomy-product_cat.html)
  • Products by Tag (taxonomy-product_tag.html)
  • Products by Attribute (taxonomy-product_attribute.html)
• Product Search Results (product-search-results.html)
• Page: Coming soon (page-coming-soon.html)
• Page: Cart (page-cart.html)
• Page: Checkout (page-checkout.html)
• Order Confirmation (order-confirmation.html)

Block themes can customize those templates in the following ways:

• It's possible to override the templates by creating a file with the same file name under the /templates folder. For example, if a block theme contains a wp-content/themes/yourtheme/templates/single-product.html template, it will take priority over the WooCommerce default Single Product template.
• Products by Category, Products by Tag and Products by Attribute templates fall back to the Product Catalog template. In other words, if a theme provides an archive-product.html template but doesn't provide a taxonomy-product_cat.html template, the Products by Category template will use the archive-product.html template. Same for the Products by Tag and Products by Attribute templates.
• It's possible to create templates for specific products and taxonomies. For example, if the theme provides a template with file name of single-product-cap.html, that template will be used when rendering the product with slug cap. Similarly, themes can provide specific taxonomy templates: taxonomy-product_cat-clothing.html would be used in the product category with slug clothing.
• Always keep in mind users can make modifications to the templates provided by the theme via the Site Editor.

Cart and Checkout page templates

The page-cart.html and page-checkout.html templates should render the content from the assigned Cart and Checkout pages. Add layout, headers, footers, and other template-level content around the page content, but keep the Cart and Checkout blocks in the corresponding page content.

WooCommerce's default page-cart.html template uses the woocommerce/page-content-wrapper block with woocommerce/store-notices, core/post-title, and core/post-content inside it:

<!-- wp:woocommerce/page-content-wrapper {"page":"cart"} -->
<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
    <!-- wp:woocommerce/store-notices /-->
    <!-- wp:post-title {"align":"wide", "level":1} /-->
    <!-- wp:post-content {"align":"wide"} /-->
</main>
<!-- /wp:group -->
<!-- /wp:woocommerce/page-content-wrapper -->

The default page-checkout.html template uses the same wrapper and store notices, but renders page content without a page title:

<!-- wp:woocommerce/page-content-wrapper {"page":"checkout"} -->
<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
    <!-- wp:woocommerce/store-notices /-->
    <!-- wp:post-content {"align":"wide"} /-->
</main>
<!-- /wp:group -->
<!-- /wp:woocommerce/page-content-wrapper -->

Use the same pattern when overriding page-cart.html or page-checkout.html in a theme. Avoid placing woocommerce/cart or woocommerce/checkout directly in these template files as a replacement for core/post-content. If the template bypasses page content, the page editor can become out of sync with what shoppers see, and WooCommerce features that inspect the assigned page content may not detect the Cart or Checkout block correctly.

Block template parts

WooCommerce also comes with two specific block template parts:

• Mini-Cart (mini-cart.html): used inside the Mini-Cart block drawer.
• Checkout header (checkout-header.html): used as the header in the Checkout template.

Similarly to the templates, they can be overridden by themes by adding a file with the same file name under the /parts folder.

Global styles

WooCommerce blocks rely on global styles for their styling. Global styles can be defined by themes via theme.json or by users via Appearance > Editor > Styles and offer several advantages over plain CSS:

• Better performance, as only the required CSS is printed into the page, reducing the bundle size to render a page.
• Can be easily customized by users via the UI.
• Gracefully handle conflicts between plugins and themes.
• Are not affected by markup or class name updates into individual blocks or components.
• Don't depend on a specific nesting order of blocks: users can freely move blocks around without styles breaking.

Example

For example, let's imagine you are building a theme and would like to customize the Product Price block styles, you can do so by adding these properties in your theme.json:

"styles": {
	"blocks": {
		"woocommerce/product-price": {
			"color": {
				"background": "#00cc00",
				"text": "#fff"
			},
			"typography": {
				"fontStyle": "italic",
				"fontWeight": "700"
			}
		}
		...
	}
	...
}

You can find more documentation on global styles in developer.wordpress.org. You can also find the list of WooCommerce blocks and their names in the docs.