@zsign/react

React wrapper around @zsign/embed for embedding a zSign signing session.

Requires React 18+ and Node 18+.

The task-oriented walkthrough lives in the embed guide.

Install

npm install @zsign/react

@zsign/embed is a runtime dependency and is installed automatically.

Allow the embedder origin first

Embedding is default-deny. A framed signing page refuses to render unless its parent origin is registered on the envelope owner's account:

curl -X PUT "$ZSIGN_BASE_URL/api/branding/embed-origins" \
  -H "Authorization: Bearer $ZSIGN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origins": ["https://app.yourcompany.com"]}'

ZSIGN_BASE_URL defaults to the public zSign API host.

Or Settings → Embedding in the dashboard. Exact match only, https required except http://localhost[:port], no paths or wildcards, max 10.

Usage

import { ZSignEmbed } from "@zsign/react";

export function SigningPanel({ signingUrl }: { signingUrl: string }) {
  return (
    <ZSignEmbed
      signingUrl={signingUrl}
      height="auto"
      onReady={() => console.log("ready")}
      onSigned={({ session_id }) => console.log("signed", session_id)}
      onError={({ message }) => console.error(message)}
    />
  );
}

signingUrl is a recipient signing link from POST /api/v1/documents/send (signing_urls) or the dashboard.

ZSignEmbed accepts every createSigningEmbed option except container (the component owns the mount node), plus className and style for that wrapper div. Changing signingUrl tears down the previous iframe and creates a new one. Callback identity changes do not.

See @zsign/embed for the live postMessage event list. Do not invent event names the signing page does not send.