Skip to main content

​
Theme Development Overview

WooCommerce works seamlessly with WordPress themes, offering flexibility for both classic PHP-based themes and modern block themes. This guide introduces the fundamentals of WooCommerce theme development and helps you choose the right approach for your project.

​
Theme Types

WooCommerce supports two distinct theme architectures, each with its own development paradigm:

​
Classic Themes

Classic themes use PHP template files and hooks to render WooCommerce content. They’ve been the standard approach since WooCommerce’s inception. Key characteristics:
  • PHP-based template files (.php)
  • Hook-driven customization system
  • Located in yourtheme/woocommerce/ directory
  • Template overrides for custom layouts
  • Direct control over HTML markup
Best for:
  • Existing WordPress sites with classic themes
  • Projects requiring deep PHP customization
  • Developers comfortable with WordPress template hierarchy
  • Themes that need backward compatibility

​
Block Themes

Block themes leverage WordPress Full Site Editing (FSE) and use HTML-based block templates. Available since WordPress 5.9 and actively developed. Key characteristics:
  • HTML-based template files (.html)
  • Styled via theme.json (global styles)
  • Visual editing through Site Editor
  • Block-based composition
  • Modern CSS architecture
Best for:
  • New projects starting with WordPress 6.0+
  • Visual, no-code customization requirements
  • Modern development workflows
  • Leveraging the WordPress block ecosystem

​
Theme Compatibility

As of WooCommerce 3.3+, all WordPress themes receive automatic compatibility with WooCommerce, even without explicit theme support. Templates render inside content areas maintaining your theme’s design.

​
Automatic Compatibility (No Theme Support)

Non-WooCommerce themes automatically include:
  • Product gallery features - Zoom, lightbox, and slider enabled by default
  • Basic template rendering - Products and shop pages display in content areas
  • Comments instead of reviews - Standard WordPress comments unless reviews are explicitly enabled

​
Declaring Theme Support

For advanced control, themes should declare WooCommerce support using add_theme_support(): 
function mytheme_add_woocommerce_support() {
    add_theme_support( 'woocommerce' );
}
add_action( 'after_setup_theme', 'mytheme_add_woocommerce_support' );
You must declare WooCommerce support if using custom template overrides. Without theme support, WooCommerce assumes the theme is incompatible and falls back to shortcode-based rendering.

​
Advanced Theme Support Options

Configure WooCommerce features when declaring support: 
function mytheme_add_woocommerce_support() {
    add_theme_support( 'woocommerce', array(
        'thumbnail_image_width' => 150,
        'single_image_width'    => 300,
        
        'product_grid'          => array(
            'default_rows'    => 3,
            'min_rows'        => 2,
            'max_rows'        => 8,
            'default_columns' => 4,
            'min_columns'     => 2,
            'max_columns'     => 5,
        ),
    ) );
}
add_action( 'after_setup_theme', 'mytheme_add_woocommerce_support' );
Configuration options:
  • thumbnail_image_width - Product thumbnail width (shop pages)
  • single_image_width - Main product image width (single product)
  • product_grid - Default, minimum, and maximum columns/rows for shop display
If image sizes aren’t declared, users can configure them via Customizer > WooCommerce > Product Images.
WooCommerce includes an advanced product gallery with zoom, lightbox, and slider functionality using Flexslider, Photoswipe, and jQuery Zoom. 
add_theme_support( 'wc-product-gallery-zoom' );
add_theme_support( 'wc-product-gallery-lightbox' );
add_theme_support( 'wc-product-gallery-slider' );
You can enable individual features selectively. Scripts only load for enabled features. If your theme provides custom gallery functionality: 
remove_theme_support( 'wc-product-gallery-zoom' );
remove_theme_support( 'wc-product-gallery-lightbox' );
remove_theme_support( 'wc-product-gallery-slider' );

​
Integration Methods

WooCommerce offers three methods for integrating with themes:
When creating woocommerce.php in your theme, you cannot override archive-product.php as woocommerce.php takes priority. This is intentional to prevent display conflicts.

​
Template Structure

WooCommerce templates reside in: 
/wp-content/plugins/woocommerce/templates/
├── archive-product.php          # Shop page
├── single-product.php           # Product page
├── taxonomy-product-cat.php     # Category archives
├── taxonomy-product-tag.php     # Tag archives
├── cart/                        # Cart templates
├── checkout/                    # Checkout templates
├── myaccount/                   # Account templates
├── emails/                      # Email templates
└── ...
Override templates by copying to: 
/wp-content/themes/yourtheme/woocommerce/
Maintain the same file structure but remove the /templates/ subdirectory.
All templates contain hooks allowing content addition/modification without editing template files. This is the preferred customization method.

​
Choosing Your Approach

1

Assess Your Project

  • New sites: Consider block themes for modern development
  • Existing classic themes: Continue with classic approach
  • Client requirements: Visual editing favors block themes
2

Evaluate Technical Requirements

  • Deep PHP customization: Classic themes
  • Visual customization: Block themes
  • Hybrid needs: Classic themes with Gutenberg blocks
3

Plan Integration Method

  • Minor styling: Hooks only (recommended)
  • Structural changes: Template overrides
  • Complete control: Custom templates + hooks
4

Declare Theme Support

Add add_theme_support() calls to enable WooCommerce features

​
Next Steps

Classic Theme Development

Learn PHP-based theme development with template files and hooks

Block Theme Development

Explore FSE, block templates, and theme.json styling

Theme Customization

CSS, hooks, child themes, and best practices

​
Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us