API Reference

Complete eSign component API

Component props

Required props

eventId · string · required

Unique identifier for this signing session

document · object · required

Document configuration

Show Properties

source · string | File | Blob · required

Document to display

mode · string

Display mode: 'full' | 'download'

viewOptions · object

View options for controlling document layout (recommended)

Show Properties

viewOptions.layout · string

Document layout: 'print' (default) or 'web'

• print - Fixed page width, displays document as it prints
• web - Content reflows to fit container (mobile/accessibility)

layoutMode · string · deprecated

Deprecated. Use viewOptions.layout instead.

• 'paginated' → viewOptions: { layout: 'print' }
• 'responsive' → viewOptions: { layout: 'web' }

layoutMargins · object · deprecated

Deprecated. No longer supported. Use CSS for margin control.

validation.scroll.required · boolean

Require scrolling to bottom before signing

onSubmit · function · required

Called when document is signed

(data: SubmitData) => void | Promise<void>

Optional props

fields · object

Field configuration

Show Properties

document · DocumentField[]

Values to inject into document

signer · SignerField[]

Interactive fields for user to complete

download · object

Download button configuration

Show Properties

fileName · string

Filename for download

label · string

Button text

component · React.Component

Custom button component

submit · object

Submit button configuration

Show Properties

label · string

Button text

component · React.Component

Custom button component

onDownload · function

Handle download action

(data: DownloadData) => void | Promise<void>

onStateChange · function

Monitor state changes

(state: SigningState) => void

onFieldChange · function

Track field changes

(field: FieldChange) => void

onFieldsDiscovered · function

Called when document fields are found

(fields: FieldInfo[]) => void

onZoomChange · function

Called when zoom level changes

(data: { zoom: number }) => void

telemetry · object

Telemetry configuration. Enabled by default with source: 'esign' metadata. See Telemetry for details.

Show properties

enabled · boolean · default: "true"

Enable or disable telemetry

metadata · Record<string, any>

Custom metadata merged with the default { source: 'esign' }

licenseKey · string

License key for SuperDoc. Passed directly to the underlying SuperDoc instance.

isDisabled · boolean

Disable all interactions

className · string

CSS class for container

style · React.CSSProperties

Inline styles for container

documentHeight · string

Height of document viewer (default: '600px')

Types

SubmitData

Data passed to onSubmit:

interface SubmitData {
  eventId: string;           // Your session ID
  timestamp: string;         // ISO timestamp
  duration: number;          // Time spent in seconds
  auditTrail: AuditEvent[];  // All events
  documentFields: DocumentField[];  // Injected values
  signerFields: SignerFieldValue[]; // User inputs
  isFullyCompleted: boolean; // All requirements met
}

DownloadData

Data passed to onDownload:

interface DownloadData {
  eventId: string;                   // Your session ID
  documentSource: string | File | Blob;  // Original document source
  fields: {
    document: DocumentField[];
    signer: SignerFieldValue[];
  };
  fileName: string;                  // Suggested filename
}

DocumentField

Values injected into document:

type FieldValue = string | boolean | number | null | undefined;
type TableFieldValue = string[][];

interface DocumentField {
  id: string;                        // Unique field ID
  type?: 'text' | 'table';           // Field type (default: 'text')
  value: FieldValue | TableFieldValue;  // The value
}

For table fields, the value is a 2D array where each inner array represents a row.

SignerField

Interactive field definition:

interface SignerField {
  id: string;                            // Required unique ID
  type: 'signature' | 'checkbox' | 'text';
  label?: string;                         // Display label
  value?: FieldValue;                     // Initial value
  validation?: {
    required?: boolean;
  };
  component?: React.ComponentType<FieldComponentProps>;
}

SigningState

Current state passed to onStateChange:

interface SigningState {
  scrolled: boolean;               // Has scrolled
  fields: Map<string, FieldValue>; // Current values
  isValid: boolean;                // Can submit
  isSubmitting: boolean;            // Currently submitting
}

AuditEvent

Timestamped interaction log:

interface AuditEvent {
  timestamp: string;
  type: 'ready' | 'scroll' | 'field_change' | 'submit';
  data?: Record<string, unknown>;
}

ViewOptions

Document view options (recommended):

interface ViewOptions {
  layout?: 'web' | 'print';  // 'print' is default
}

LayoutMargins (Deprecated)

Deprecated since v2.0. Use CSS for margin control.

interface LayoutMargins {
  top?: number;    // pixels
  bottom?: number; // pixels
  left?: number;   // pixels
  right?: number;  // pixels
}

SuperDocESignHandle

Ref type for accessing component methods:

interface SuperDocESignHandle {
  getState: () => SigningState;
  getAuditTrail: () => AuditEvent[];
  reset: () => void;
  updateFieldInDocument: (field: DocumentField) => void;
  setZoom: (percent: number) => void;
  getZoom: () => number;
}

Ref methods

Access via ref:

import { useRef } from 'react';
import type { SuperDocESignHandle } from '@superdoc-dev/esign';

const ref = useRef<SuperDocESignHandle>(null);

// Get current state
const state = ref.current?.getState();

// Get audit trail
const audit = ref.current?.getAuditTrail();

// Reset everything
ref.current?.reset();

// Update field in the document programatically
ref.current?.updateFieldInDocument({ id: '1', value: 'Updated value' });

// Control zoom
ref.current?.setZoom(150);       // Zoom to 150%
const zoom = ref.current?.getZoom(); // Get current zoom

return <SuperDocESign ref={ref} ... />

Available methods

• getState() - Returns current SigningState
• getAuditTrail() - Returns audit events array
• reset() - Clear all state and start over
• updateFieldInDocument() - Update a document field by id
• setZoom(percent) - Set zoom level as a percentage (e.g., 150 for 150%)
• getZoom() - Returns current zoom level as a percentage (default: 100)

Field components

Default components

The component provides default implementations for all field types. You can import and extend them:

import { SignatureInput, CheckboxInput } from '@superdoc-dev/esign';

// Use directly
<SignatureInput 
  value={value}
  onChange={handleChange}
  isDisabled={false}
  label="Sign here"
/>

Custom component props

All custom field components receive:

interface FieldComponentProps {
  value: FieldValue;           // Current value
  onChange: (value: FieldValue) => void;
  isDisabled: boolean;         // Disabled state
  isValid?: boolean;           // Validation state
  label?: string;              // Field label
  error?: string;              // Error message
}

CSS classes

Target these classes for styling:

• .superdoc-esign-container - Main wrapper
• .superdoc-esign-document - Document viewer area
• .superdoc-esign-controls - Controls section
• .superdoc-esign-fields - Field container
• .superdoc-esign-actions - Button container
• .superdoc-esign-btn - Default buttons

Import types

All types are exported:

import type {
  SuperDocESignProps,
  SuperDocESignHandle,
  DocumentConfig,
  SubmitData,
  DownloadData,
  SigningState,
  DocumentField,
  SignerField,
  FieldValue,
  TableFieldValue,
  FieldChange,
  AuditEvent,
  FieldComponentProps,
  LayoutMargins  // deprecated
} from '@superdoc-dev/esign';

Utils

import { textToImageDataUrl } from '@superdoc-dev/esign';

textToImageDataUrl

Converts text to a base64 image data URL. This is useful if you want to generate the same base64 image that is created for typed signatures on the document.

const imageDataUrl = textToImageDataUrl(text: string);