Skip to main content
Complete eSign component API

​
Component props

​
Required props

​
eventId
string
required
Unique identifier for this signing session
​
document
object
required
Document configuration
​
onSubmit
function
required
Called when document is signed
(data: SubmitData) => void | Promise<void>

​
Optional props

​
fields
object
Field configuration
​
download
object
Download button configuration
​
submit
object
Submit button configuration
​
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
​
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;
}

​
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' });

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

​
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);