@korala/react

@korala/react

React components and hooks for embedding Korala document signing in your application.

Installation

pnpm add @korala/react

Usage

KoralaSigner Component

The main component for embedding the signing experience:

import { KoralaSigner } from '@korala/react';

function SigningPage({ signingToken }: { signingToken: string }) {
  return (
    <KoralaSigner
      token={signingToken}
      signingUrl="https://sign.yourdomain.com" // Optional, defaults to env var
      className="w-full h-[600px]"
      onReady={() => console.log('Embed ready')}
      onLoaded={(data) => console.log('Document loaded:', data)}
      onViewed={(data) => console.log('Document viewed:', data)}
      onFieldFilled={(data) => console.log('Field filled:', data)}
      onSigned={(data) => console.log('Document signed:', data)}
      onDeclined={(data) => console.log('Document declined:', data)}
      onError={(data) => console.error('Error:', data)}
    />
  );
}

Props

Prop	Type	Required	Description
token	string	Yes	The signer's access token
signingUrl	string	No	Base URL of the signing app. Defaults to NEXT_PUBLIC_KORALA_SIGNING_URL env var
className	string	No	CSS class for the iframe
style	CSSProperties	No	Inline styles for the iframe
allowedOrigins	string[]	No	Restrict postMessage origins
onReady	(data) => void	No	Called when embed is initialized
onLoaded	(data) => void	No	Called when document is loaded
onViewed	(data) => void	No	Called when signer views the document
onFieldFilled	(data) => void	No	Called when a field is filled
onSigned	(data) => void	No	Called when signing is complete
onDeclined	(data) => void	No	Called when signer declines
onError	(data) => void	No	Called on errors

useKoralaEvents Hook

Alternative to callbacks - listen to all events via a hook:

import { useKoralaEvents } from '@korala/react';

function SigningStatus() {
  const { status, events, lastEvent } = useKoralaEvents();

  return (
    <div>
      <p>Status: {status}</p>
      <p>Events received: {events.length}</p>
    </div>
  );
}

Returns:

• status: 'loading' | 'ready' | 'loaded' | 'viewed' | 'signing' | 'signed' | 'declined' | 'error'
• events: Array of all received events
• lastEvent: Most recent event
• clearEvents: Function to clear stored events

Event Data Types

LoadedEventData

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

SignedEventData

{
  documentId: string;
  signerId: string;
  signedAt: string;
}

DeclinedEventData

{
  documentId: string;
  signerId: string;
  reason?: string;
  declinedAt: string;
}

ErrorEventData

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

Environment Variables

Set in your .env.local:

NEXT_PUBLIC_KORALA_SIGNING_URL=http://localhost:3003