@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

| Prop | Required | Type | |------|----------|------| | embedUrl | Yes | string | | tokenProvider | Yes | (context: TokenProviderContext) => Promise<TokenProviderResult> | | iframeOptions | No | IframeOptions | | tokenOptions | No | TokenOptions | | displayOptions | No | DisplayOptions | | devOptions | No | DevOptions | | showLoadingOn | No | EmbedStatus[] — Which statuses show the loading overlay. Default: ['INITIALIZING', 'RELOADING', 'REFRESHING']. Ignored when renderLoading is not set. | | renderLoading | No | (props: { status: EmbedStatus }) => ReactNode — Custom UI shown while loading. When not set, the iframe's built-in loading is used. |

Callbacks

| Callback | Payload | When | |----------|---------|------| | onStatusChanged | (payload: { type: 'STATUS_CHANGED', status: EmbedStatus, previousStatus: EmbedStatus }) => void | See core SDK | | onParamChanged | (payload: { type: 'PARAM_CHANGED', params: EncodedParam[] }) => void | See core SDK | | onExecuteSqlsTriggered | (payload: { type: 'EXECUTE_SQLS_TRIGGERED', params: EncodedParam[] }) => void | See core SDK | | onExecutionSucceeded | (payload: { type: 'EXECUTION_SUCCEEDED' }) => void | See core SDK | | onExecutionFailed | (payload: { type: 'EXECUTION_FAILED', errorMessage: string }) => void | See core SDK | | onError | (err: EmbedError) => void | Init, reload, or token auto-refresh failed |

Ref (EmbedReactRef)

| Property | Type | Description | |----------|------|-------------| | reload() | () => Promise<boolean> | Re-fetches token and params; returns false on failure (error reported via onError) | | status | 'CREATED' \| 'INITIALIZING' \| 'RELOADING' \| 'REFRESHING' \| 'READY' \| 'DESTROYED' | Current embed state |

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