@signvoy/react

Official React SDK for the Signvoy e-signature API. Drop the embedded signing experience into any React app and react to signing events with typed callbacks.

Installation

npm install @signvoy/react
# or
pnpm add @signvoy/react

react >= 18 is a peer dependency.

How it works

@signvoy/react is browser-safe — it never handles your secret API key. The flow is:

1. On your server, mint a scoped, single-use signing URL with @signvoy/node via POST /v1/embed/session.
2. Send that url to the browser.
3. Render <SignvoyEmbed url={url} /> and handle lifecycle events.

Quick start

import { SignvoyEmbed } from "@signvoy/react";

export function SignRoom({ sessionUrl }: { sessionUrl: string }) {
  return (
    <SignvoyEmbed
      url={sessionUrl}
      style={{ height: 720, borderRadius: 12 }}
      onReady={() => console.log("signing UI loaded")}
      onComplete={(e) => {
        console.log("signed!", e.documentId);
      }}
      onDecline={(e) => console.log("declined", e.reason)}
      onError={(e) => console.error(e.message)}
    />
  );
}

Minting the session URL (server side)

import Signvoy from "@signvoy/node";

const signvoy = new Signvoy({
  apiKey: process.env.SIGNVOY_API_KEY!,
  workspaceId: process.env.SIGNVOY_WORKSPACE_ID!,
});

// e.g. in an API route
const session = await signvoy.request("POST", "/embed/session", {
  documentId,
  documentRecipientId,
});
// → { url, expiresAt, documentId, documentRecipientId }

Headless usage

Render your own iframe and drive it with the hook:

import { useSignvoyEmbed } from "@signvoy/react";

function CustomEmbed({ url }: { url: string }) {
  const { status, error } = useSignvoyEmbed({
    url,
    onComplete: (e) => console.log("done", e.documentId),
  });

  return (
    <>
      {status === "loading" && <Spinner />}
      {status === "error" && <p>{error?.message}</p>}
      <iframe src={url} title="Signing" />
    </>
  );
}

Shared configuration (optional)

import { SignvoyProvider } from "@signvoy/react";

<SignvoyProvider signingOrigin="https://sign.acme.com">
  <App />
</SignvoyProvider>;

signingOrigin restricts which origin may post events to your page. It's only needed when you self-host the signing UI; for signvoy.com-hosted signing the origin is derived from each session URL automatically.

Documentation

• Embedded signing guide
• Quickstart guide
• API Reference

Get an API key

Sign up at signvoy.com → Workspace Settings → API Keys.

Contributing

See CONTRIBUTING.md. The generated/ directory is auto-generated from the OpenAPI spec — edit src/ instead.

License

MIT — see LICENSE.