@codatum/embed-react

React integration for Codatum Signed Embed. Provides a single component that wraps the core SDK. All of @codatum/embed is re-exported so you can use this package as a single entry point (one version, no split).

For options, types, events, and programmatic API details, see @codatum/embed.

Installation

pnpm add @codatum/embed-react
# or
npm install @codatum/embed-react

Requires React 18+ (peer dependency).

Usage

import { EmbedReact } from "@codatum/embed-react";

const embedUrl = "https://app.codatum.com/protected/workspace/xxx/notebook/yyy";
const tokenProvider = async () => {
  const res = await fetch("/api/embed-token", { method: "POST" });
  const data = await res.json();
  return { token: data.token };
};

function App() {
  return (
    <EmbedReact
      embedUrl={embedUrl}
      tokenProvider={tokenProvider}
      iframeOptions={{ theme: "LIGHT", locale: "ja" }}
      onStatusChanged={(e) => console.log("Status", e.status)}
      onParamChanged={(e) => console.log("Params", e.params)}
      onExecuteSqlsTriggered={(e) => console.log("Execute", e.params)}
      onError={(e) => console.error(e)}
    />
  );
}

Calling reload from the parent

Use a ref and call the exposed reload() method. It returns true on success and false on failure (errors are reported via onError; it does not throw).

import { useRef } from "react";
import { EmbedReact, type EmbedReactRef } from "@codatum/embed-react";

function App() {
  const embedRef = useRef<EmbedReactRef>(null);

  async function onFilterChange() {
    const ok = await embedRef.current?.reload();
    if (!ok) console.warn("reload failed — see onError");
  }

  return (
    <>
      <button type="button" onClick={onFilterChange}>
        Reload
      </button>
      <EmbedReact
        ref={embedRef}
        embedUrl="..."
        tokenProvider={...}
        onError={handleError}
      />
    </>
  );
}

Custom loading UI

Use renderLoading to show custom UI while loading. showLoadingOn controls which statuses show it (default: INITIALIZING / RELOADING / REFRESHING).

<EmbedReact
  embedUrl={embedUrl}
  tokenProvider={tokenProvider}
  renderLoading={() => <MySpinner />}
/>

Show only on first load:

<EmbedReact
  embedUrl={embedUrl}
  tokenProvider={tokenProvider}
  showLoadingOn={["INITIALIZING"]}
  renderLoading={() => <FullPageLoader />}
/>

Branch by status:

<EmbedReact
  embedUrl={embedUrl}
  tokenProvider={tokenProvider}
  renderLoading={({ status }) =>
    status === "INITIALIZING" ? <FullPageLoader /> : <SubtleBar />
  }
/>

Changing props at runtime

Props are read once at mount. To apply new values (e.g. a different embedUrl or iframeOptions), use key to force a remount:

<EmbedReact key={embedUrl} embedUrl={embedUrl} tokenProvider={tokenProvider} />

API

Option types and behavior (e.g. iframeOptions, tokenOptions, displayOptions, devOptions) are the same as in @codatum/embed. The component uses its root element as the iframe container (no container prop).

Props

Callbacks

Ref (EmbedReactRef)

Need a custom container or full control? Use createEmbed() from this package (or @codatum/embed) inside a useEffect and call instance.destroy() in the cleanup.

See also

• Versioning and changelog: Versioning
• Security and deployment: Security and deployment
• Supported environments: Supported environments