React SDK

npm install @korala/react
# or
yarn add @korala/react
# or
pnpm add @korala/react

import { KoralaSigner } from '@korala/react';
 
function SigningPage({ token }: { token: string }) {
  return (
    <KoralaSigner
      token={token}
      signingUrl="https://app.korala.ai"
      style={{ width: '100%', height: '800px' }}
      onSigned={(data) => {
        console.log('Document signed!', data.documentId);
      }}
      onError={(data) => {
        console.error('Signing error:', data.message);
      }}
    />
  );
}

<KoralaSigner
  token={signingToken}
  signingUrl="https://app.korala.ai"
  className="signing-frame"
  style={{ width: '100%', height: '100%' }}
  allowedOrigins={['https://app.korala.ai']}
  onReady={(data) => console.log('Ready:', data.version)}
  onLoaded={(data) => console.log('Document loaded:', data.documentName)}
  onViewed={(data) => console.log('Viewed at:', data.viewedAt)}
  onFieldFilled={(data) => console.log(`${data.filledFields}/${data.totalRequiredFields} fields`)}
  onSigned={(data) => console.log('Signed:', data.documentId)}
  onDeclined={(data) => console.log('Declined:', data.reason)}
  onError={(data) => console.error(data.message)}
/>

<KoralaSigner token={token} ownConsent />

api_request "POST" "/api/v1/signing/$SIGNER_TOKEN/consent"

import { KoralaSigner } from '@korala/react';
import type { KoralaSignerTheme } from '@korala/react';
 
const theme: KoralaSignerTheme = {
  accentColor: '#2563EB',                      // hex color
  borderRadius: 8,                              // 0-24 px
  fontFamily: 'Inter, system-ui, sans-serif',   // CSS font-family
  backgroundColor: '#EEF2FF',                   // page background (hex)
  logoUrl: 'https://cdn.acme.com/logo.png',     // header logo (white-label plans)
};
 
<KoralaSigner
  token={signingToken}
  theme={theme}
  style={{ width: '100%', height: '100%' }}
  onSigned={(data) => console.log('Signed:', data.documentId)}
/>

import { KoralaSignaturePad } from '@korala/react';
 
function CaptureSignature() {
  const [signature, setSignature] = useState<string | null>(null);
 
  return (
    <KoralaSignaturePad
      width={600}
      height={200}
      penColor="#000000"
      onSignatureCreated={({ imageDataUrl }) => {
        setSignature(imageDataUrl);
      }}
      onClear={() => setSignature(null)}
    />
  );
}

import { useKoralaEvents } from '@korala/react';
 
function SigningStatus() {
  const { status, events, lastEvent } = useKoralaEvents({
    signingUrl: 'https://app.korala.ai',
  });
 
  return (
    <div>
      <p>Status: {status}</p>
      <p>Events received: {events.length}</p>
      {status === 'signed' && <p>Document signed.</p>}
    </div>
  );
}

import { KoralaSigner, useKoralaSignerRef } from '@korala/react';
 
function ControlledSigner({ token }: { token: string }) {
  const { ref, close, getStatus, gotoField, gotoPage, getFields } =
    useKoralaSignerRef();
 
  return (
    <div>
      <KoralaSigner ref={ref} token={token} />
      <button onClick={close}>Close signing</button>
      <button onClick={getStatus}>Check status</button>
      <button onClick={() => gotoField()}>Go to next field</button>
    </div>
  );
}

<KoralaSigner ref={ref} token={token} showNavigation />

const [commands, setCommands] = useState<string[]>([]);
 
<KoralaSigner
  ref={ref}
  token={token}
  onReady={(data) => setCommands(data.commands ?? [])}
/>;
 
{commands.includes('goto_field') && (
  <button onClick={() => gotoField()}>Go to next field</button>
)}

function FieldNavigator({ token }: { token: string }) {
  const { ref, gotoField, getFields } = useKoralaSignerRef();
  const [fields, setFields] = useState<KoralaFieldSummary[]>([]);
 
  // The list is available once the document has loaded.
  const load = async () => setFields((await getFields())?.fields ?? []);
 
  return (
    <div>
      <KoralaSigner ref={ref} token={token} onLoaded={load} onFieldFilled={load} />
      <ol>
        {fields.map((field) => (
          <li key={field.fieldId}>
            <button onClick={() => gotoField(field.fieldId)}>
              {field.label ?? field.fieldType}: page {field.pageNumber}
              {field.filled ? ' ✓' : ''}
            </button>
          </li>
        ))}
      </ol>
    </div>
  );
}

interface KoralaGotoFieldResult {
  fieldId: string | null;
  pageNumber: number | null;
  outcome: 'arrived' | 'unreachable' | 'not_found';
}

interface KoralaFieldSummary {
  fieldId: string;
  fieldType: string;
  label: string | null;
  pageNumber: number;    // 1-based
  required: boolean;
  filled: boolean;
  shared: boolean;       // another signer's field that you may fill
}
 
interface KoralaGetFieldsResult {
  fields: KoralaFieldSummary[];
  nextFieldId: string | null;  // what the signer's own button targets next
}

interface ReadyEventData {
  version: string;  // Embed protocol version
  token: string;    // Signer access token
}

interface ConsentAcceptedEventData {
  documentId: string;
  signerId: string;
  consentedAt: string;  // ISO timestamp
}

interface LoadedEventData {
  documentId: string;
  documentName: string;
  signerName: string;
  signerEmail: string;
  totalFields: number;
  requiredFields: number;
}

interface ViewedEventData {
  documentId: string;
  signerId: string;
  viewedAt: string;  // ISO 8601
}

interface FieldFilledEventData {
  fieldId: string;
  fieldType: string;           // 'signature' | 'initials' | 'date' | 'text' | 'checkbox'
  pageNumber?: number;         // 1-based page; absent on signing apps older than the SDK
  filledFields: number;
  totalRequiredFields: number; // live; see below
}

interface SignedEventData {
  documentId: string;
  signerId: string;
  signedAt: string;       // ISO 8601
  redirectUrl?: string;
}

interface DeclinedEventData {
  documentId: string;
  signerId: string;
  reason?: string;
  declinedAt: string;  // ISO 8601
}

interface ErrorEventData {
  code: string;
  message: string;
  recoverable: boolean;
}

import { isKoralaEvent } from '@korala/react';
 
window.addEventListener('message', (event) => {
  if (isKoralaEvent(event)) {
    console.log('Korala event:', event.data.type);
  }
});

import { useState } from 'react';
import { KoralaSigner } from '@korala/react';
 
export function SigningFlow() {
  const [status, setStatus] = useState<'form' | 'signing' | 'complete'>('form');
  const [token, setToken] = useState<string | null>(null);
 
  async function startSigning(name: string, email: string) {
    // Call your backend to create a document and get a signing token
    const res = await fetch('/api/create-signing-session', {
      method: 'POST',
      body: JSON.stringify({ name, email }),
    });
    const { signingToken } = await res.json();
    setToken(signingToken);
    setStatus('signing');
  }
 
  if (status === 'signing' && token) {
    return (
      <div style={{ height: '100vh' }}>
        <KoralaSigner
          token={token}
          signingUrl={process.env.NEXT_PUBLIC_KORALA_URL}
          style={{ width: '100%', height: '100%', border: 'none' }}
          onSigned={() => setStatus('complete')}
          onDeclined={(data) => {
            alert(`Signing declined: ${data.reason}`);
            setStatus('form');
          }}
          onError={(data) => {
            console.error('Error:', data.message);
            if (!data.recoverable) setStatus('form');
          }}
        />
      </div>
    );
  }
 
  if (status === 'complete') {
    return <p>Document signed.</p>;
  }
 
  return (
    <form onSubmit={(e) => {
      e.preventDefault();
      const fd = new FormData(e.currentTarget);
      startSigning(fd.get('name') as string, fd.get('email') as string);
    }}>
      <input name="name" placeholder="Name" required />
      <input name="email" type="email" placeholder="Email" required />
      <button type="submit">Start signing</button>
    </form>
  );
}