React hooks
How to run a ceremony from a React client component, with the @esigncomply/react hooks or with the browser SDK directly.
@esigncomply/react is a thin layer of hooks over the browser SDK. It ships no visual components: you build every element of the signing screen, and the hooks connect those elements to the ceremony.
npm install @esigncomply/react @esigncomply/browser
react (18 or later) and @esigncomply/browser are peer dependencies. The package is an ES module with type declarations. Its built file starts with "use client", so the hooks run in the browser only.
What the package contains
| Export | Kind | Purpose |
|---|---|---|
useCeremony |
Hook | Attaches to one session by its client token and follows it: status, outstanding steps, findings, the last error. |
useDocument |
Hook | Reports the presentation of one pinned document version for an element you render. |
EsignComplyError |
Class | The error class of the browser SDK, exported again so instanceof works without a second import. |
CeremonyStatus, UseCeremonyOptions, UseCeremonyResult, UseDocumentOptions, UseDocumentResult |
Types | The hook signatures, described below. |
Ceremony, CompleteResult, Finding, PresentationMode, StepResult |
Types | Exported again from @esigncomply/browser. |
import { useCeremony, useDocument, EsignComplyError } from "@esigncomply/react";
import type { Ceremony, CeremonyStatus, UseCeremonyResult, UseDocumentResult } from "@esigncomply/react";
Both hooks call the browser SDK. Everything on the browser SDK page applies: the methods of the ceremony object, the events each one records, the errors, and the requirements.
Never. Do not import
esigncomply(the server package) or readESIGNCOMPLY_API_KEYin a file marked"use client". The browser receives the session client token (esc_ct_...) and nothing else.
useCeremony
function useCeremony(options: UseCeremonyOptions): UseCeremonyResult;
interface UseCeremonyOptions {
clientToken: string | null | undefined;
apiUrl?: string;
}
interface UseCeremonyResult {
ceremony: Ceremony | null;
status: CeremonyStatus;
remainingSteps: string[];
findings: Finding[];
error: EsignComplyError | null;
canComplete: boolean;
}
type CeremonyStatus = "idle" | "attaching" | "ready" | "error" | "completed";
| Option | Description |
|---|---|
clientToken |
The session client token from your server. While it is null, undefined or empty, the hook stays idle and attaches nothing. |
apiUrl |
The api_url of the session your server created. Pass it for sessions outside the US region. |
The hook calls EsignComply.attach({ clientToken, apiUrl }) in an effect and returns:
| Field | Description |
|---|---|
ceremony |
The attached Ceremony from @esigncomply/browser, or null until the attach has resolved. |
status |
idle: no token yet. attaching: the attach is running. ready: attached. error: the attach failed or the session expired. completed: the signing act was recorded. |
remainingSteps |
The steps still outstanding, from ceremony.remainingSteps(). It follows the page: unticking the box puts intent.captured back. Empty until the ceremony is ready. |
findings |
Conformance findings that did not pass, the latest for each step. A new result for a step replaces the earlier findings of that step. Each has rule, status, message, fix and doc_url. |
error |
The reason the attach failed, or the last error a ceremony method raised, as an EsignComplyError with code, rule and fix. null when there is none. After the session expires it is an error with code client_token_expired. |
canComplete |
true when status is ready and signature.applied is the only step left. Use it to enable the action control. |
How the hook attaches:
- Once per session. One attachment exists per pair of
clientTokenandapiUrl. Every component that callsuseCeremonywith the same pair shares it and gets the sameceremonyobject. - Strict mode. In development React runs effects twice. The session is still attached once, and
client.attachedis recorded once. - Cleanup. The ceremony is destroyed when the last component that uses the token unmounts. You do not call
ceremony.destroy()yourself. - Retry. A failed attach is forgotten, so a later mount with the same token tries again.
- A method error does not change
status. A rejectedpresentDocumentorcompletesetserrorand leavesstatusatready. Only a failed attach or an expired session setsstatustoerror.
useDocument
function useDocument<T extends Element = HTMLElement>(
ceremony: Ceremony | null | undefined,
options: UseDocumentOptions,
): UseDocumentResult<T>;
interface UseDocumentOptions {
versionId: string | null | undefined;
mode: PresentationMode; // "hyperlink" | "inline" | "scrollbox"
}
interface UseDocumentResult<T extends Element> {
ref: (element: T | null) => void;
presented: boolean;
error: EsignComplyError | null;
}
| Parameter | Description |
|---|---|
ceremony |
The ceremony from useCeremony. While it is null the hook waits. |
versionId |
A document version pinned on the session (documents[].version_id of the session your server created). While it is empty the hook waits. |
mode |
hyperlink: put ref on the link. inline or scrollbox: put ref on the element that holds the document text. |
| Field | Description |
|---|---|
ref |
A callback ref. It goes on the link or on the container. |
presented |
true once document.presented is recorded for this version. |
error |
The EsignComplyError of a presentation that failed, or null. |
Once the ceremony, the element and the version ID all exist, the hook calls ceremony.presentDocument({ versionId, mode, link }) for a hyperlink, or ceremony.presentDocument({ versionId, mode, container }) for the other two modes. The browser SDK treats the same element and version as one presentation, so a strict-mode rerun sends nothing twice. For a download or print control, mark it with data-esc-download or data-esc-print inside the container or on the linked document page.
Every other step is a method on ceremony: observeAssent, verify.start, verify.confirm, verify.passkey, presentDisclosure, reviewPresented, complete, cancel and the rest. Call them from effects and event handlers.
Rules for React components
- Client only. Call the hooks in a file marked
"use client". They attach in an effect, never during render. - Start when the form mounts. Render the form with the client token already in its props, so the ceremony attaches before the signer acts. Do not attach on submit.
- Refs, not selectors. Pass DOM elements from refs. Call ceremony methods after the elements are mounted.
- Do not drive the controls. Every checkbox starts unchecked and every typed-name field starts empty. Leave the checkbox uncontrolled, or control it with state that starts
false. Never setchecked, call.click()or submit on the user's behalf. The SDK reports the control as it finds it (CR-01). - Disable, do not hide. Keep the action button disabled until
canCompleteistrue. - Confirm on the server. The result of
ceremony.complete()is delivered to the browser. Grant access only after your server has confirmed the record. See Server confirmation.
Signup form example
The parent server component, or a server action, creates the session with the Node SDK and passes four values down: clientToken, apiUrl and the two pinned version IDs. The form runs an L1 ceremony with a checkbox and a button. finishSignup is your server action. It confirms the record with the secret key before it creates the account.
"use client";
import { useEffect, useRef, useState, type FormEvent } from "react";
import { EsignComplyError, useCeremony, useDocument } from "@esigncomply/react";
import { finishSignup } from "./actions"; // server action: (form: FormData, recordId: string) => Promise<void>
type Props = { clientToken: string; apiUrl: string; tosVersionId: string; privacyVersionId: string };
export function SignupForm({ clientToken, apiUrl, tosVersionId, privacyVersionId }: Props) {
const { ceremony, status, error, canComplete } = useCeremony({ clientToken, apiUrl });
const tos = useDocument<HTMLAnchorElement>(ceremony, { versionId: tosVersionId, mode: "hyperlink" });
const privacy = useDocument<HTMLAnchorElement>(ceremony, { versionId: privacyVersionId, mode: "hyperlink" });
const assentRef = useRef<HTMLDivElement>(null);
const checkboxRef = useRef<HTMLInputElement>(null);
const submitRef = useRef<HTMLButtonElement>(null);
const [message, setMessage] = useState<string | null>(null);
const [pending, setPending] = useState(false);
// Observe the assent controls once both documents are presented.
// A failure reaches the hook's `error`, so the returned promise needs no handler here.
useEffect(() => {
if (!ceremony || !tos.presented || !privacy.presented) return;
void ceremony.observeAssent({
region: assentRef.current, // notice, links, checkbox, button
checkbox: checkboxRef.current,
submit: submitRef.current,
});
}, [ceremony, tos.presented, privacy.presented]);
// The signing act, from the signer's real click.
async function onSubmit(event: FormEvent<HTMLFormElement>) {
event.preventDefault();
if (!ceremony) return;
const form = new FormData(event.currentTarget);
setPending(true);
setMessage(null);
try {
const result = await ceremony.complete(); // { recordId, receipt, verifyUrl, status }
await finishSignup(form, result.recordId);
} catch (err) {
// A refusal (4xx, or one made in the browser) carries a message and a fix: keep the form.
// Anything else is inconclusive: never proceed without a confirmed record.
const refused = err instanceof EsignComplyError && err.code !== "network_error" && err.status < 500;
setMessage(refused ? err.message : "We could not confirm whether your acceptance was recorded. Please wait while we check.");
} finally {
setPending(false);
}
}
const shown =
message ??
(status === "error" ? "We could not start the signing step. Reload the page to try again." : null) ??
tos.error?.message ??
privacy.error?.message ??
error?.message ??
null;
return (
<form onSubmit={onSubmit}>
<label htmlFor="email">Email</label>
<input id="email" name="email" type="email" autoComplete="email" required />
<div ref={assentRef}>
<p>
By checking the box and clicking Create account, you agree to the{" "}
<a ref={tos.ref} href="/legal/terms">Terms of Service</a> and acknowledge the{" "}
<a ref={privacy.ref} href="/legal/privacy">Privacy Notice</a>.
</p>
<label>
<input ref={checkboxRef} type="checkbox" name="agree" /> I agree to the Terms of Service and Privacy Notice
</label>
<button ref={submitRef} type="submit" disabled={!canComplete || pending}>
Create account
</button>
</div>
{shown ? <p role="alert">{shown}</p> : null}
</form>
);
}
What the example relies on:
- The checkbox is uncontrolled and has no
defaultChecked. It starts unchecked and only the user changes it. - The notice, both links, the checkbox and the button sit inside the one element passed as
region. Nothing sits between the notice and the button. - The links point at document pages on your own domain that render the registered version inside
<article data-esc-document>. See the Next.js guide. canCompleteturns true when the documents and the notice are recorded and the box is ticked. If the user unticks the box, the button is disabled again.- A rejected call carries a rule ID and a
fix. In test mode the SDK also logs both to the browser console. During development you can renderfindingsfromuseCeremonyto see each rule, message and fix on the page.
Typed-name signatures
For an NDA or a contract, pass an empty text field instead of a checkbox. The name leaves the page once, with the signing act.
const nameRef = useRef<HTMLInputElement>(null);
useEffect(() => {
if (!ceremony || !nda.presented) return;
void ceremony.observeAssent({ region: assentRef.current, typedName: nameRef.current, submit: submitRef.current });
}, [ceremony, nda.presented]);
// <input ref={nameRef} type="text" name="legal_name" autoComplete="off" /> (no defaultValue, no value prop)
Here nda is the result of useDocument for the document being signed. Do not prefill the field from the account profile, and do not render the name in a cursive font as the signature. For email verification before signing, call ceremony.verify.start() and ceremony.verify.confirm() from your own buttons: see L2 verification.
Without the hooks
The hooks are optional. @esigncomply/browser works in a client component on its own: call EsignComply.attach() inside useEffect, keep the ceremony in state, subscribe to change to track remainingSteps(), and call destroy() in the cleanup. In strict mode guard the async attach with a flag and destroy a ceremony that resolves after cleanup. The methods are on the browser SDK page.
Server components and server actions
Keep three things on the server: the secret key, session creation, and confirmation of the record. A typical split in the Next.js App Router:
| Piece | Where | Uses |
|---|---|---|
| Create the session | Server action or route handler | esigncomply, ESIGNCOMPLY_API_KEY |
| Run the ceremony | Client component | @esigncomply/react or @esigncomply/browser, the client token |
| Confirm the record and grant access | Server action or webhook route | esigncomply, ESIGNCOMPLY_API_KEY |
The full walkthrough, including the Supabase table and the webhook, is in the Next.js guide.