woocommerce-blocks

What this skill does

# 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
   <?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
   <?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 [];
       }
   }
   ```

2. **Create the inner block React component**

   ```javascript
   // src/blocks/gift-message/index.js
   import { registerCheckoutBlock } from "@woocommerce/blocks-checkout";
   import { __ } from "@wordpress/i18n";
   import { useEffect, useState } from "@wordpress/element";
   import {
     useExtensionCartUpdateData,
     extensionCartUpdate,
   } from "@woocommerce/blocks-checkout";

   const Block = ({ children, checkoutExtensionData }) => {
     const [giftMessage, setGiftMessage] = useState("");

     // Persist gift message to cart extension data
     const handleChange = (e) => {
       const value = e.target.value;
       setGiftMessage(value);
       extensionCartUpdate({
         namespace: "my-checkout-fields",
         data: { gift_message: value },
       });
     };

     return (
       <div className="wc-block-checkout__gift-message">
         <label htmlFor="gift-message">
           {__("Gift message (optional)", "my-checkout-fields")}
         </label>
         <textarea
           id="gift-message"
           value={giftMessage}
           onChange={handleChange}
           placeholder={__("Write your message here...", "my-checkout-fields")}
           rows={3}
           maxLength={200}
         />
         <span className="character-count">{giftMessage.length}/200</span>
       </div>
     );
   };

   registerCheckoutBlock({
     metadata: {
       name: "my-checkout-fields/gift-message",
       title: "Gift Message",
       category: "woocommerce",
       parent: ["woocommerce/checkout-shipping-methods-block"],
       attributes: {},
     },
     component: Block,
   });
   ```

3. **Extend the Store API to persist custom data**

   ```php
   <?php
   // Extend the Store API Cart schema to accept and store custom extension data
   add_action('woocommerce_blocks_loaded', function () {
       woocommerce_store_api_register_endpoint_data([
           'endpoint'        => Automattic\WooCommerce\StoreApi\Schemas\V1\CartSchema::IDENTIFIER,
           'namespace'       => 'my-checkout-fields',
           'schema_callback' => function () {
               return [
                   'gift_message' => [
                       'description' => 'Gift message for the order',
                       'type'        => 'string',
                       'context'     => ['view', 'edit'],
                       'readonly'    => false,
                       'sanitize_callback' => 'sanitize_textarea_field',
                   ],
               ];
           },
           'schema_type' => ARRAY_A,
       ]);

       // Save the gift message to WC session when cart is updated
       woocommerce_store_api_register_update_callback([
           'namespace' => 'my-checkout-fields',
           'callback'  => function (array $data) {
               if (isset($data['gift_message'])) {
                   WC()->session->set('gift_message', sanitize_textarea_field($data['gift_message']));
               }
           },
       ]);
   });

   // Transfer session data to order meta on checkout
   add_action('woocommerce_checkout_order_created', function ($order) {
       $gift_message = WC()->session->get('gift_message', '');
       if (!empty($gift_message)) {
           $order->update_meta_data('_gift_message', $gift_message);
           $order->save();
       }
   });
   ```

4. **Use SlotFills for injecting UI without inner blocks**

   SlotFills are simpler than inner blocks — they inject content into predefined slots:

   ```javascript
   // src/frontend.js
   import { registerPlugin } from "@wordpress/plugins";
   import { ExperimentalOrderMeta } from "@woocommerce/blocks-checkout";
   import { __ } from "@wordpress/i18n";
   import { useSelect } from "@wordpress/data";
   import { CART_STORE_KEY } from "@woocommerce/block-data";

   const CartUpsellBanner = () => {
     const cartTotal = useSelect((select) => {
       const cart = select(CART_STORE_KEY).getCartData();
       return cart?.totals?.total_items;
     });

     const freeShippingThreshold = 5000; // $50.00 in cents
     const remaining = freeShippingThreshold - parseInt(cartTotal ?? "0");

     if (remaining <= 0) return null;

     return (
       <div className="free-shipping-banner">
         {__(`Add $${(remaining / 100).toFixed(2)} more for free shipping!`, "my-checkout-fields")}
       </div>
     );
   };

   registerPlugin("my-cart-upsell", {
     render: () => (
       <ExperimentalOrderMeta>
         <CartUpsellBanner />
       </ExperimentalOrderMeta>
     ),
     scope: "woocommerce-checkout",
   });
   ```

5. **Build and enqueue assets with `@wordpress/scripts`**

   ```json
   // package.json
   {
     "scripts": {
       "build": "wp-scripts build src/frontend.js src/blocks/gift-message/index.js",
       "start": "wp-scripts start src/frontend.js src/blocks/gift-message/index.js"
     },
     "devDependencies": {
       "@wordpress/scripts": "^30.0.0"
     }
   }
   ```

   ```json
   // src/blocks/gift-message/block.json
   {
     "$schema": "https://schemas.wp.org/trunk/block.json",
     "apiVersion": 3,
     "name":