Your privacy choices

We use necessary cookies, and others only if you allow them. You can change your mind at any time.

FS

@particle-academy/fancy-sign-ui

@particle-academy/fancy-sign-ui

React surfaces for fancy-sign, built from react-fancy, for simple electronic signatures: the signer ceremony (email code, consent, document with per-page view reports, signature pad, a fresh code to sign, or decline), the organisation admin's per-page switch, envelope setup with staged send and void, the timeline with browser-reported events labelled, the certificate of completion and a verifier. Controlled, with stable data-fancy-sign-* handles; an agent can manage an envelope and can never sign one. A React-free client on ./client.

UI surfaceTS
Part of Fancy Sign — 2 packages, one productSee the family
UI surface
Live demos with source for every export.
ButtonlivebetaCardRK
$npm install @particle-academy/fancy-sign-ui
Pairs with

API surface

Headless package — drive it from code or an agent. No component grid.

This package renders no UI surface. It exposes a typed code API; issues are tracked on GitHub.
readmeREADME.mdView on GitHub →

@particle-academy/fancy-sign-ui

React surfaces for e-signature envelopes: the signer's ceremony, the sender's envelope setup, the audit timeline, the certificate of completion and a verifier. Plus a React-free client (./client) for the wire contract.

Designed to support simple electronic signatures (SES): consent and intent captured, signer verified by email one-time code, a hash-chained audit trail, and a sealed final document.

Whether an electronic signature is appropriate for a given document, and which level it needs, depends on the jurisdiction and the document type. Have it reviewed by a lawyer before relying on it.

Part of the Fancy Sign family. The backends serve the same JSON, so the same surfaces work against either one:

Package Runtime Role
particle-academy/fancy-sign (Composer) PHP / Laravel Server: envelopes, fields, email codes, audit chain, completion record and seal, verify.
@particle-academy/fancy-sign (npm) Node Server twin (planned).
@particle-academy/fancy-sign-ui (npm) Browser This package. React surfaces + ./client.

Pre-1.0. Breaking changes land in MINOR releases until 1.0.0. Read CHANGELOG.md before upgrading a minor.


For agents. This package is not listed on the Fancy MCP catalog server yet. The server, https://ui.particle.academy/mcp (streamable HTTP, no API key; MCP id fancy-ui), lists the released Fancy packages with install commands and docs. How an agent installs and uses this package is in AGENTS.md.

Install

npm install @particle-academy/fancy-sign-ui

Everything is a peer. This package has an empty dependencies and keeps it that way:

npm install react react-dom @particle-academy/react-fancy tailwindcss

Import the stylesheet once:

import "@particle-academy/fancy-sign-ui/styles.css";

Tailwind v4 does not scan node_modules, and these surfaces render react-fancy components, so point Tailwind at react-fancy's dist beside @import "tailwindcss";:

@source '../node_modules/@particle-academy/react-fancy/dist/**/*.{js,cjs,mjs}';

Quickstart

The client

import { createSignClient, SignError } from "@particle-academy/fancy-sign-ui/client";

const client = createSignClient({ baseUrl: "https://app.example.com/fancy-sign" });

try {
  const envelope = await client.getEnvelope("01JC...");
} catch (err) {
  if (err instanceof SignError && err.code === "not_found") {
    // ...
  }
}

One method per endpoint. Every refusal is the kit-wide error envelope ({ "error", "message", "requestId" }; on a 422, "error": "validation_failed" with the fancy-sign code as its one item in errors) and becomes a SignError whose requestId is kept and whose code is from the closed set (otp_invalid, otp_locked, consent_required, fields_incomplete, ...). A code outside that set is reported as unknown_error with the raw value in serverCode, so a UI branching on otp_locked cannot be fooled by a code it does not know. No response at all is network_error; a 5xx is server_error.

The signer session from the view code is kept inside the client and sent as X-Fancy-Sign-Session. It is never put in component state.

The signer

import { SignerCeremony } from "@particle-academy/fancy-sign-ui";

<SignerCeremony token={tokenFromUrl} client={client} />;

The flow: request a view code, enter the 6 digits; agree to sign electronically (the host's disclosure text, sent back with its version); read the document; fill the fields; draw or type a signature; request a fresh signing code; Sign. Or Decline, which requires a reason. Or Request changes (with fancy-sign 0.3.0 or later): a required message to the sender, bounded like a decline reason, after which the envelope stays open and the signer can still sign or decline. The button is disabled, with a note, once the signer has asked max_change_requests times.

With fancy-sign 0.6 an envelope may sign in order (settings.order: "sequential"). A signer who opens a link before their turn sees a "not your turn yet" panel ([data-fancy-sign-panel="waiting"]) and nothing to act on.

Sign stays disabled until consent is recorded, every required field is complete, a signature exists, and a 6-digit signing code is entered. signBlockers(state) returns what is missing, so a host can say why.

Controlled:

const [state, setState] = useState(initialCeremonyState());
<SignerCeremony token={token} client={client} value={state} onChange={setState} />;

The document. Pass renderPage={(n) => ...} to render pages yourself; each page is then observed, and a page.viewed beacon (page and time on screen) is sent once it has been on screen for minDwellMs (default 1500 ms), at most once per page per pageViewIntervalMs (default 30 s) and at most maxPageViewReports times (default 200). Render the pages from the bytes onDocument(pdf) hands you. Without renderPage, the PDF is shown whole, and no per-page claim is made. In every mode the ceremony opens the as-sent PDF through the signer's session once: that is the server-observed document.opened, and signing is refused until it has happened. These beacons are claims from the signer's browser, and every surface here labels them as such.

Data mode (fancy-sign 0.7, settings.mode: "data"). The envelope signs the host's own data, an opaque JSON object, and the host renders it with its current template:

<SignerCeremony
  token={token}
  client={client}
  renderer="quote-v7 @ shop 2026.11.19"
  renderData={(quote, ctx) => (
    <QuotePage quote={quote} signature={ctx.renderField("buyer-sig")} onLayout={ctx.reportLayout} />
  )}
/>

The ceremony fetches the data through the signer's session (the server-observed document.opened), canonicalises it (fsig-data-1) and checks its hash against the envelope's data_sha256. Only then does it call renderData with the parsed object; on a mismatch it renders nothing and Sign stays blocked. ctx gives the template fields, renderField(id) (the ceremony's own control, which the signer presses), onLocate(handler) (fired by the checklist's Show button), now (the envelope's sent_at) and reportLayout({ pages }), which posts a document.rendered claim carrying renderer once per layout change. The fields checklist stays as a complete fallback. Nothing about the presentation is stored on the envelope, so a new template or a new release of this package reaches envelopes already sent. The package seals the data and the signing evidence; how the data was displayed to each signer is the host application's. The ./data entry (no React) exports canonicalData and dataSha256 for hosts that compute data_sha256 in JavaScript.

The sender

import { EnvelopeSetup, SignFieldPalette, EnvelopeTimeline } from "@particle-academy/fancy-sign-ui";

<EnvelopeSetup
  value={setup}
  onChange={setSetup}
  envelopeStatus={envelope.status}
  onSend={() => client.sendEnvelope(envelope.id).then(refresh)}
  onVoid={(reason) => client.voidEnvelope(envelope.id, reason).then(refresh)}
/>;

<SignFieldPalette signers={setup.signers} value={draft} onChange={setDraft} onPlace={addField} />;

<EnvelopeTimeline events={await client.listEvents(envelope.id)} />;

EnvelopeSetup edits the title, signers (name, email, order) and settings (per_page, step_up, expires_at). Pass orgPerPage (from client.getOrgSettings()) and the per-page select is locked to an organisation's setting when its admin has turned one on. <OrgSigningSettings canEdit onSave /> is that admin's switch. The level is shown fixed as SES and the seal as none; nothing else is built yet. Send and Void are staged for confirmation by default (pendingMode, default true), and Void always needs a reason.

Where a field lands on the page is computed by the backend's layout, never chosen by hand, so SignFieldPalette picks a kind, a signer and an anchor (final_page, every_page, or a document node) and emits a FieldDraft.

Certificate and verification

<CompletionCertificate completion={envelope.completion} events={events} />
<SignatureVerifier client={client} />

SignatureVerifier takes the final PDF, its completion.json and optionally the events, posts them to /verify, and shows the named reason for any failure (seal_invalid, final_hash_mismatch, prefix_mismatch, chain_broken, ...).

An honest limit: in this phase the seal is checked by this verifier against the host's published public key. A PDF reader shows no signature panel for it. The original document stays a byte-for-byte prefix of the final file, so anyone can check the signed content did not change without any tool of ours.


Human+ contract

Every interactive surface here is controlled (value + onChange, the FULL next state, JSON-serialisable), carries stable data-fancy-sign-* handles on every interactive element, and reports each mutation through an optional onActivity callback with an AgentActivity-shaped event.

What an agent can do: read envelopes and timelines, edit a draft (signers, settings, fields), propose a send, a void or a reminder for a human to confirm, and verify a completed document.

What an agent cannot do, by design: verify a code, accept consent, adopt a signature, sign, decline, or request changes. Those acts belong to the signer, and an agent able to do them would empty the evidence of meaning. No prop, handle or callback here completes them, and activity events never carry a one-time code or signature points.

Signer-written text (a decline reason, a request for changes, a typed name) is rendered as plain text, never as HTML.

Personal data

The audit trail records IP addresses and user agents. Say so in your privacy notice, and set a retention period on the backend.

API

  • ./client: createSignClient, SignError, isSignErrorCode, toStateError, and every wire type (Envelope, Signer, Field, Mark, SignEvent, Completion, VerifyResult, SignerView, SignErrorCode, ...).
  • Root: everything above, plus SignerCeremony, SignaturePad, SignatureField, InitialsField, DateSignedField, SignFieldPalette, EnvelopeSetup, EnvelopeTimeline, CompletionCertificate, SignatureVerifier, and the pure helpers (signBlockers, setupProblems, MARK_LIMITS, startStroke, extendStroke, validateMark, ...).

A drawn signature is { kind: "drawn", strokes }, points normalised to [0, 1] with y pointing down, capped at 64 strokes and 2048 points. A typed one is { kind: "typed", text }, at most 128 characters. It is never an image.

License

MIT

What next
Click any component for a live demo, props, and source — or install the package and go.