woocommerce-blocks

WooCommerce Blocks

Overview

WooCommerce Blocks replaces the classic shortcode-based cart and checkout with React-powered Gutenberg blocks. Custom plugins can extend the Checkout Block by registering inner blocks (custom fields inside checkout steps), using SlotFills (inject UI into predefined injection points), and extending the Store API to save and retrieve custom data. The block-based checkout is the default for new WooCommerce stores since version 8.3.

When to Use This Skill

• When adding custom fields to the checkout form (gift message, delivery date picker, VAT number)
• When injecting promotional content or upsell banners into the cart or checkout block
• When creating a custom checkout step with additional business logic
• When replacing the legacy shortcode checkout on existing WooCommerce sites
• When building a plugin that extends checkout behavior without modifying core templates

Core Instructions

1. Register a Checkout Inner Block

   Inner blocks are React components that render inside a checkout step. They require PHP block registration + a JS/React frontend:

   <?php
   // my-checkout-fields/my-checkout-fields.php
   add_action('woocommerce_blocks_loaded', function () {
       if (!class_exists('Automattic\WooCommerce\Blocks\Integrations\IntegrationInterface')) {
           return;
       }
       require_once __DIR__ . '/class-my-checkout-integration.php';
       add_action(
           'woocommerce_blocks_checkout_block_registration',
           function ($integration_registry) {
               $integration_registry->register(new My_Checkout_Integration());
           }
       );
   });
   

   <?php
   // class-my-checkout-integration.php
   use Automattic\WooCommerce\Blocks\Integrations\IntegrationInterface;
   
   class My_Checkout_Integration implements IntegrationInterface {
       public function get_name() {
           return 'my-checkout-fields';
       }
   
       public function initialize() {
           $this->register_block_frontend_scripts();
           $this->register_inner_block();
       }
   
       private function register_block_frontend_scripts() {
           wp_register_script(
               'my-checkout-fields-frontend',
               plugin_dir_url(__FILE__) . 'build/frontend.js',
               ['wc-blocks-checkout', 'wp-element'],
               filemtime(plugin_dir_path(__FILE__) . 'build/frontend.js'),
               true
           );
       }
   
       private function register_inner_block() {
           register_block_type(plugin_dir_path(__FILE__) . 'build/blocks/gift-message/block.json');
       }
   
       public function get_script_handles() {
           return ['my-checkout-fields-frontend'];
       }
   
       public function get_editor_script_handles() {
           return [];
       }
   
       public function get_script_data() {
           return [];
       }
   }