@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