Add e-signatures to a React app
Embed e-signatures in a React app with coss.com Sign. Create a request on your server, mount the signing page, and keep the sealed PDF.
Your server creates a signature request and a signing session, a React component shows the
signing page with mountSigning from coss/sign, and a webhook says when the sealed PDF is
ready. The server code uses Next.js route handlers; any server works. For the overview, see
e-signatures.
Allow your app to embed the signing page
Install the SDK (npm install coss) and add your app's origin to the Sign settings, here or in
the dashboard. Sandbox environments also accept http://localhost:3000 while you develop.
await ...({ : ["https://app.example.com"] });Create a signature request on the server
Ask your signed-in user to sign a PDF, inline as base64 or uploaded first with
coss.sign.documents.upload(). delivery: "embedded" means they sign in your app instead of from
an emailed link, and client_ref (your user id) goes into the audit trail. Anchors like
{{signature:signer_1}} in the PDF place fields without coordinates
(fields and anchors).
const { : , } = await ...({
: "Services agreement",
: [{ : "agreement.pdf", : }],
: [
{
: .,
: .,
: "embedded",
: .,
: [{ : "signature", : "{{signature:signer_1}}" }],
},
],
: { : "ctr_123" }, // comes back in every sign_request.* webhook
});
// Keep request.id and request.signers[0].id with your contract.Create a signing session for the embedded signer
Your app vouches for who the signer is, so create a session only for that signed-in user, when
they open the page. Each call makes a new session, valid for an hour by default and at most 24.
Sessions are refused for email signers, for requests that aren't sent and for signers who
already signed or declined.
// app/api/contracts/[id]/session/route.ts
import { } from "coss";
const = new ();
export async function (: , : { : <{ : string }> }) {
const = await ();
const = await ((await .)., .);
if (!) return new (null, { : 404 });
const { , } = ;
const { : , } = await ...(, );
if () return .({ : . }, { : 409 });
// The token is in the URL's fragment: never log it.
return .({ : . });
}Embed the signing page in a React component
mountSigning returns an embed whose destroy() removes the iframe and stops listening, which is
the effect's cleanup. The iframe grows with its content, up to the window's height.
"use client";
import { , , } from "react";
import { , type } from "coss/sign";
export function ({ }: { : string }) {
const = <>(null);
const [, ] = <string | null>(null);
(() => {
let : { (): void } | undefined;
let = false;
const = (: ) => {
if (. === "signed") ("Thanks, you signed.");
if (. === "declined") ("You declined to sign.");
if (. === "error") (`This link can't be used (${.}).`);
};
(`/api/contracts/${}/session`, { : "POST" })
.(() => .() as <{ : string }>)
.(({ }) => {
if ( || !.) return;
= ({ , : ., });
});
return () => {
= true;
?.();
};
}, []);
return ? <>{}</> : < ={} />;
}Events arrive in order: ready, viewed, then signed or declined, plus error when the link
is invalid or expired. signed carries request_status, completed when this signer was the
last. They are UI hints: keep your records from webhooks.
Get the sealed PDF from the sign_request.completed webhook
When the last signer signs, coss.com seals the document and sends sign_request.completed. Download
the sealed PDF then. An event can arrive more than once, so deduplicate by its id.
// app/api/webhooks/coss/route.ts
import { , } from "coss";
const = new ();
export async function (: ) {
const = ..!;
const = await (await .(), ., );
if (. === "sign_request.completed") {
const { , } = .;
const { : } = await ...();
if () await (.contract_id!, );
}
return new (null);
}viewed, signer_signed, declined, canceled and expired events show progress too. See
completion and the audit trail.
Use templates for repeat documents
For a contract you send again and again, make a template once, with a role
per party (client, company) and merge fields filled from your data. Then replace
coss.sign.requests.create() with coss.sign.templates.createRequest(templateId, { signers, merge_fields }), giving each signer a role and delivery: "embedded". Everything after it
(sessions, the component, the webhook) stays the same.
Test with a sandbox key
With a coss_test_… key, requests work end to end on the real signing page: it says the signing
has no legal effect, the PDF gets a test seal, no emails reach anyone and nothing is billed.
coss listen forwards webhooks to your local server and coss trigger sign_request.completed
sends a sample one. See testing Sign.
Next steps
- Embedded signing: sessions, events and settings.
- Templates: roles, merge fields and the embedded template builder.
- Email signing: signers who sign from an emailed link.
- Sign: what's included and pricing.
Last updated
On This Page