React and Hydrogen

Render the custom element in a client component and pass the current Shopify product, variant and cart IDs. Load the SDK once at application-shell level. Connect Headless SDK first. For a custom React UI without the block, use Headless API.

The example below uses React’s standard refs and effects and avoids requiring a global custom-element JSX type. It is an integration pattern, not an official Antla React package.

React wrapper

import { useEffect, useRef } from "react";

type Props = {
  sdkKey: string;
  productId: string;
  variantId: string;
  cartId?: string;
  cartUrl?: string;
  language?: string;
};

// Load the CDN SDK once in your app shell. For Next.js App Router,
// add "use client"; at the top of this file.
export function AntlaTryOn({
  sdkKey, productId, variantId, cartId, cartUrl = "/cart", language,
}: Props) {
  const host = useRef<HTMLDivElement>(null);
  const block = useRef<HTMLElement | null>(null);

  useEffect(() => {
    const element = block.current ?? document.createElement("antla-block");
    const attributes: Record<string, string | undefined> = {
      "variant-id": variantId,
      "product-id": productId,
      "cart-id": cartId,
      "cart-url": cartUrl,
      language,
      "sdk-key": sdkKey,
    };
    for (const [name, value] of Object.entries(attributes)) {
      if (value === undefined || value === "") element.removeAttribute(name);
      else if (element.getAttribute(name) !== value) element.setAttribute(name, value);
    }
    if (!block.current) {
      block.current = element;
      host.current?.appendChild(element);
    }
  }, [sdkKey, productId, variantId, cartId, cartUrl, language]);

  useEffect(() => () => {
    block.current?.remove();
    block.current = null;
  }, []);

  return <div ref={host} />;
}

For Next.js App Router, place "use client"; at the top of the wrapper. Load the CDN script once through your framework’s application-shell script mechanism. The wrapper sets initial attributes before attachment and updates changed values afterward. Do not evaluate the browser SDK during server rendering.

Hydrogen cart ownership

Hydrogen’s cart may live in a server-side session. Setting cart-id lets the SDK use that cart. It does not notify Hydrogen that a mutation occurred. See Cart integration and attribution.

For the SDK on a Hydrogen page:

• Create the shopper’s cart through your storefront before mounting the SDK, and pass the full cart ID.
• Revalidate your storefront’s cart when the user returns from the modal or opens the cart.
• If the block creates a new cart, persist its new cart-id through your storefront’s own authenticated session flow.

If you need complete control over cart mutation, skip the block and use the Headless API with your own result UI.

Do not assume an antla_product_added_to_cart event is emitted by this SDK. Watching the cart-id attribute can detect a changed ID. It does not detect every line mutation on an existing cart.

Route lifecycle

Unmount the element when leaving the product view. The SDK stops its browser-side work on disconnection. Preserve a single element for normal variant selection so that changing a dropdown does not reset the entire flow.

Do not interpret unmount, closing a modal or aborting a browser request as server-job cancellation. A queued job can still finish.

Variant edge cases

The SDK currently loads the first 100 variants and first 30 images without pagination. A product whose selected variant is outside that fetched set needs a tested custom API integration or an SDK update.

The block prefers a supplied matching variant, otherwise an available one, then a first-variant fallback. Your product page should hide try-on for unavailable products according to your shopping UX. The API’s generation validation does not replace Storefront availability checks.

Test in your framework

Verify SSR and hydration, client navigation, slow script loading, script failure, existing and newly created carts, cart revalidation, sold-out variants and a browser with storage unavailable. See Launch checklist.