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)}
/>

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
};
 
<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({
    allowedOrigins: ['https://app.korala.ai'],
  });
 
  return (
    <div>
      <p>Status: {status}</p>
      <p>Events received: {events.length}</p>
      {status === 'signed' && <p>Document signed successfully!</p>}
    </div>
  );
}

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

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

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'
  filledFields: number;
  totalRequiredFields: number;
}

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 successfully!</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>
  );
}