@vitra/image-creator-react

React component for the Vitra Image Creation Platform iframe embed. Peer-deps react >= 18 (compatible with Next.js 13/14/15 hosts).

Install

npm install @vitra/image-creator-react

Quick start — Translate.photo integration

Backend (Next.js App Router):

// app/api/vitra/session/route.ts
import { VitraClient } from "@vitra/image-creator-node";
import { auth } from "@/lib/auth";

const vitra = new VitraClient({
  appId: "translate-photo",
  sharedSecret: process.env.VITRA_IC_SECRET!,
});

export async function POST(req: Request) {
  const user = await auth(req);
  const session = await vitra.session.create({
    userId: user.id,
    parentOrigin: "https://app.translate.photo",
  });
  return Response.json(session);
}

Frontend:

import { ImageCreatorEmbed } from "@vitra/image-creator-react";

export function CreatePage({ brandColor }: { brandColor: string }) {
  return (
    <ImageCreatorEmbed
      sessionEndpoint="/api/vitra/session"
      theme={{ "--brand-500": brandColor }}
      onAssetReady={(asset) => ingestAsset(asset.signed_url)}
      style={{ minHeight: 600 }}
    />
  );
}

That's the entire integration. ~20 lines across both files.

Props

| Prop | Type | Purpose | |------|------|---------| | sessionEndpoint | string | Required. Your host endpoint that returns a bootstrap token. | | baseUrl | string | Override Vitra base URL (staging, self-hosted). | | theme | Record<string,string> | CSS custom properties to inject into the iframe. Reactive — changes don't remount. | | onReady | () => void | Iframe mounted + bootstrap exchanged. | | onAssetReady | (e) => void | A generated asset is available — signed URL + metadata. | | onAssetFailed | (e) => void | Generation failed. | | onCreditUsed | (e) => void | Credits captured. | | onError | (e) => void | Unrecoverable error. | | onResize | (e) => void | Iframe height changed. | | className, style | React | Forwarded to the container <div>. |

Imperative handle

For advanced control, pass a ref:

import { useRef } from "react";
import {
  ImageCreatorEmbed,
  type ImageCreatorEmbedHandle,
} from "@vitra/image-creator-react";

function Page() {
  const embed = useRef<ImageCreatorEmbedHandle>(null);
  return (
    <>
      <button onClick={() => embed.current?.refreshSession()}>
        Refresh session
      </button>
      <ImageCreatorEmbed ref={embed} sessionEndpoint="/api/vitra/session" />
    </>
  );
}

StrictMode

<ImageCreatorEmbed /> is safe under React 18 StrictMode. The effect cleanup unmounts the iframe on the first (intentional) teardown and the second mount starts cleanly — no duplicate iframes, no lingering listeners.

Stability policy

v0.x is pre-1.0; the prop surface may change. From 1.0 onward every exported type is semver-stable.

License

Apache-2.0.