Shopify Checkout UI Extensions

Overview

Checkout UI Extensions replace checkout.liquid (deprecated August 2025) with sandboxed, React-like components at specific checkout targets. They run in isolation with no DOM access and a strict 64KB bundle limit, using Shopify's component library for consistent, accessible UIs.

Prerequisites

• Shopify CLI 3.x+ and a Shopify Partners app
• Node.js 18+,

  @shopify/ui-extensions-react

  package
• Development store with checkout extensibility enabled

Instructions

Step 1: Configure the Extension

# extensions/checkout-banner/shopify.extension.toml
api_version = "2025-01"
type = "ui_extension"

[[extensions.targeting]]
module = "./src/Checkout.tsx"
target = "purchase.checkout.block.render"

[extensions.capabilities]
api_access = true
network_access = false

Step 2: Build with UI Components

import {
  reactExtension, Banner, BlockStack, Text, useSettings,
} from "@shopify/ui-extensions-react/checkout";

export default reactExtension("purchase.checkout.block.render", () => <CheckoutBanner />);

function CheckoutBanner() {
  const { banner_text } = useSettings();
  return (
    <BlockStack spacing="tight">
      <Banner status="info">{banner_text || "Free shipping over $50!"}</Banner>
    </BlockStack>
  );
}

Step 3: Read Checkout Data with Hooks

import {
  useApplyMetafieldsChange, useTotalAmount, useShippingAddress, TextField,
} from "@shopify/ui-extensions-react/checkout";

function DeliveryNote() {
  const applyMetafieldsChange = useApplyMetafieldsChange();
  return (
    <TextField
      label="Delivery instructions"
      onChange={(value) => applyMetafieldsChange({
        type: "updateMetafield",
        namespace: "custom", key: "delivery_note",
        valueType: "string", value,
      })}
    />
  );
}

Step 4: Bundle Size Strategies

shopify app build --verbose  # Check output size
# Import only what you use — each component adds ~1-3KB
# Avoid lodash, date-fns, zod — use native JS
# Split into multiple extensions if approaching 64KB

See extension-targets.md for all targets, ui-components.md for components, and bundle-optimization.md for size strategies.

Output

• Checkout UI extension rendering at the configured target point
• Custom data collection via metafield writes from checkout
• Merchant-configurable settings via the extension editor
• Sandboxed execution with no impact on checkout performance

Error Handling

EXTENSION_LOAD_FAILED

--verbose

fetch

window

CHECKOUT_COMPLETION_BLOCKED

block_progress

Examples

Adding a Custom Field to Checkout

Collect delivery instructions or gift messages by rendering a text input at a specific checkout target and saving the value as a cart metafield.

See Extension Targets for all available targets and placement options.

Building a Reusable Checkout Banner

Create a merchant-configurable promotional banner using Shopify's UI component library with proper accessibility.

See UI Components for available components and their key props.

Optimizing Extension Bundle Size

Your checkout extension is approaching the 64KB limit. Apply tree-shaking, dependency auditing, and extension splitting strategies.

See Bundle Optimization for size measurement and reduction techniques.

Resources

• Checkout UI Extensions Overview
• Extension Targets Reference
• UI Component Library
• checkout.liquid Migration Guide