Getting Started with WooCommerce Blocks

Introduction to WooCommerce block development, Gutenberg integration, and available block types

Getting Started with WooCommerce Blocks

WooCommerce Blocks provide a modern, block-based approach to building e-commerce experiences in WordPress. Built on the WordPress Gutenberg editor, WooCommerce Blocks enable you to create dynamic, customizable shopping experiences using React and TypeScript.

What are WooCommerce Blocks?

WooCommerce Blocks are reusable components that extend the WordPress Block Editor to provide e-commerce functionality. They leverage the WordPress Gutenberg architecture to deliver:

• Modern React Components: Built with TypeScript and React for type safety and maintainability
• Server-Side Rendering: PHP integration for optimal performance and SEO
• Store API Integration: RESTful API for cart, checkout, and product data
• Extensibility: Hooks, filters, and Slot Fills for customization

Block Architecture

WooCommerce blocks follow the WordPress Block API specification:

{
  "apiVersion": 3,
  "name": "woocommerce/product-collection",
  "title": "Product Collection",
  "category": "woocommerce",
  "description": "Display a collection of products from your store.",
  "supports": {
    "align": ["wide", "full"],
    "html": false,
    "interactivity": true
  },
  "attributes": {
    "query": { "type": "object" },
    "displayLayout": { "type": "object" }
  }
}

Types of WooCommerce Blocks

Product Blocks

Display and interact with products:

• Product Collection: Display filterable product collections with customizable queries
• Product Gallery: Showcase product images with thumbnails and large image views
• Product Filters: Enable filtering by attributes, price, ratings, and taxonomy
• Product Reviews: Display customer reviews with pagination and filtering
• Single Product: Render individual product details and metadata

Cart & Checkout Blocks

Handle the purchase flow:

• Cart Block: Modern cart experience with line items, totals, and coupon support
• Checkout Block: Multi-step checkout with address fields, payment methods, and order summary
• Mini Cart: Slide-out cart accessible from anywhere on the site

Cart and Checkout blocks are highly extensible with Slot Fills, filters, and custom inner blocks. See the Extensible Blocks guide for details.

Product Editor Blocks

Build custom product editing interfaces:

• Product Fields: Input controls for name, price, description, inventory
• Generic Blocks: Reusable form components (sections, tabs, subsections)
• Custom Blocks: Extension points for plugin-specific product data

Example product editor block structure:

import { useWooBlockProps } from '@woocommerce/block-templates';
import { useEntityProp } from '@wordpress/core-data';
import { InputControl } from '@wordpress/components';

export function ProductNameEdit({ attributes }) {
  const blockProps = useWooBlockProps(attributes);
  const [name, setName] = useEntityProp('postType', 'product', 'name');

  return (
    <div {...blockProps}>
      <InputControl
        value={name}
        onChange={setName}
        placeholder="e.g. 12 oz Coffee Mug"
      />
    </div>
  );
}

Gutenberg Integration

WooCommerce blocks integrate seamlessly with WordPress Gutenberg:

Block Registration

Blocks are registered using the WordPress Block API:

import { registerBlockType } from '@wordpress/blocks';
import metadata from './block.json';
import { Edit, Save } from './edit';

registerBlockType(metadata, {
  icon: {
    src: <MyCustomIcon />,
    foreground: '#874FB9',
  },
  edit: Edit,
  save: Save,
});

Block Context

Blocks can share data through context:

{
  "providesContext": {
    "queryId": "queryId",
    "query": "query",
    "displayLayout": "displayLayout"
  },
  "usesContext": ["templateSlug", "postId"]
}

Inner Blocks

Create nested block structures:

import { useInnerBlocksProps } from '@wordpress/block-editor';

export function Edit() {
  const innerBlocksProps = useInnerBlocksProps(
    {},
    {
      template: [
        ['woocommerce/product-image'],
        ['woocommerce/product-title'],
        ['woocommerce/product-price']
      ],
      allowedBlocks: ['woocommerce/product-*']
    }
  );

  return <div {...innerBlocksProps} />;
}

Development Environment Setup

Build System

WooCommerce blocks use @wordpress/scripts for build configuration:

// webpack.config.js
const defaultConfig = require('@wordpress/scripts/config/webpack.config');
const WooCommerceDependencyExtractionWebpackPlugin = require('@woocommerce/dependency-extraction-webpack-plugin');

module.exports = {
  ...defaultConfig,
  plugins: [
    ...defaultConfig.plugins.filter(
      (plugin) =>
        plugin.constructor.name !== 'DependencyExtractionWebpackPlugin'
    ),
    new WooCommerceDependencyExtractionWebpackPlugin(),
  ],
};

Dependency Extraction

The WooCommerceDependencyExtractionWebpackPlugin automatically:

• Externalizes WordPress and WooCommerce dependencies
• Generates .asset.php files with dependency lists and versions
• Maps imports to global variables (e.g., @woocommerce/blocks-checkout → window.wc.wcBlocksCheckout)

JavaScript Import

import { registerCheckoutFilters } from '@woocommerce/blocks-checkout';

Registering Scripts

Enqueue blocks using the generated asset file:

<?php
function my_extension_register_blocks() {
  $script_path = '/build/index.js';
  $script_url = plugins_url($script_path, __FILE__);
  
  $script_asset_path = dirname(__FILE__) . '/build/index.asset.php';
  $script_asset = file_exists($script_asset_path)
    ? require $script_asset_path
    : ['dependencies' => [], 'version' => '1.0.0'];
  
  wp_register_script(
    'my-extension-blocks',
    $script_url,
    $script_asset['dependencies'],
    $script_asset['version'],
    true
  );
  
  wp_enqueue_script('my-extension-blocks');
}
add_action('enqueue_block_editor_assets', 'my_extension_register_blocks');

Available Components

WooCommerce provides reusable React components:

import {
  Button,
  Label,
  ValidationInputError,
  CheckboxControl,
  Panel
} from '@woocommerce/blocks-components';

import {
  useValidateCheckout,
  useStoreCart
} from '@woocommerce/blocks-checkout';

View all available components in the WooCommerce Storybook under “WooCommerce Blocks → External components”.

Data Stores

Access WooCommerce data using WordPress data stores:

import { useSelect } from '@wordpress/data';

function MyComponent() {
  const cartData = useSelect((select) => {
    return select('wc/store/cart').getCartData();
  });

  return <div>Cart total: {cartData.totals.total_price}</div>;
}

All WooCommerce Interactivity API stores are private (lock: true). Do not rely on internal store structure as it may change without notice. Use exported selectors and actions only.

Next Steps

Extensible Blocks

Learn how to extend Cart, Checkout, and Product Collection blocks with filters and Slot Fills

Tutorials

Follow step-by-step guides to build custom WooCommerce blocks

Store API

Extend the REST API to add custom data to cart and checkout

Block Reference

Explore detailed API documentation for filters, hooks, and components

Resources

• WordPress Block Editor Handbook
• WooCommerce Blocks GitHub
• WooCommerce Storybook
• @woocommerce/dependency-extraction-webpack-plugin