> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdoc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

Complete eSign component API

## Component props

### Required props

**eventId** `string` *required*

Unique identifier for this signing session

**document** `object` *required*

Document configuration

**Properties**

**source** `string | File | Blob` *required*

Document to display

**mode** `string`

Display mode: `'full' | 'download'`

**viewOptions** `object`

View options for controlling document layout (recommended)

**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

```typescript theme={null}
(data: SubmitData) => void | Promise<void>
```

### Optional props

**fields** `object`

Field configuration

**Properties**

**document** `DocumentField[]`

Values to inject into document

**signer** `SignerField[]`

Interactive fields for user to complete

**download** `object`

Download button configuration

**Properties**

**fileName** `string`

Filename for download

**label** `string`

Button text

**component** `React.Component`

Custom button component

**submit** `object`

Submit button configuration

**Properties**

**label** `string`

Button text

**component** `React.Component`

Custom button component

**onDownload** `function`

Handle download action

```typescript theme={null}
(data: DownloadData) => void | Promise<void>
```

**onStateChange** `function`

Monitor state changes

```typescript theme={null}
(state: SigningState) => void
```

**onFieldChange** `function`

Track field changes

```typescript theme={null}
(field: FieldChange) => void
```

**onFieldsDiscovered** `function`

Called when document fields are found

```typescript theme={null}
(fields: FieldInfo[]) => void
```

**onZoomChange** `function`

Called when zoom level changes

```typescript theme={null}
(data: { zoom: number }) => void
```

**telemetry** `object`

Telemetry configuration. Enabled by default with `source: 'esign'` metadata. See [Telemetry](https://docs.superdoc.dev/resources/telemetry.md) for details.

**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`:

```typescript theme={null}
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`:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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`:

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

### AuditEvent

Timestamped interaction log:

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

### ViewOptions

Document view options (recommended):

```typescript theme={null}
interface ViewOptions {
  layout?: 'web' | 'print';  // 'print' is default
}
```

### LayoutMargins (Deprecated)

> [!WARNING]
>
> Deprecated since v2.0. Use CSS for margin control.

```typescript theme={null}
interface LayoutMargins {
  top?: number;    // pixels
  bottom?: number; // pixels
  left?: number;   // pixels
  right?: number;  // pixels
}
```

### SuperDocESignHandle

Ref type for accessing component methods:

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

## Ref methods

Access via ref:

```tsx theme={null}
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:

```jsx theme={null}
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:

```typescript theme={null}
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:

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

## Utils

```typescript theme={null}
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.

```typescript theme={null}
const imageDataUrl = textToImageDataUrl(text: string);
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.