> ## Documentation Index
> Fetch the complete documentation index at: https://superdoc-caio-pizzol-docs-ai-core-preset.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

Complete eSign component API

## Component props

### Required props

<ParamField path="eventId" type="string" required>
  Unique identifier for this signing session
</ParamField>

<ParamField path="document" type="object" required>
  Document configuration

  <Expandable title="Properties">
    <ParamField path="source" type="string | File | Blob" required>
      Document to display
    </ParamField>

    <ParamField path="mode" type="string">
      Display mode: `'full' | 'download'`
    </ParamField>

    <ParamField path="viewOptions" type="object">
      View options for controlling document layout (recommended)

      <Expandable title="Properties">
        <ParamField path="viewOptions.layout" type="string">
          Document layout: `'print'` (default) or `'web'`

          * `print` - Fixed page width, displays document as it prints
          * `web` - Content reflows to fit container (mobile/accessibility)
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="layoutMode" type="string" deprecated>
      **Deprecated.** Use `viewOptions.layout` instead.

      * `'paginated'` → `viewOptions: { layout: 'print' }`
      * `'responsive'` → `viewOptions: { layout: 'web' }`
    </ParamField>

    <ParamField path="layoutMargins" type="object" deprecated>
      **Deprecated.** No longer supported. Use CSS for margin control.
    </ParamField>

    <ParamField path="validation.scroll.required" type="boolean">
      Require scrolling to bottom before signing
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="onSubmit" type="function" required>
  Called when document is signed

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

### Optional props

<ParamField path="fields" type="object">
  Field configuration

  <Expandable title="Properties">
    <ParamField path="document" type="DocumentField[]">
      Values to inject into document
    </ParamField>

    <ParamField path="signer" type="SignerField[]">
      Interactive fields for user to complete
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="download" type="object">
  Download button configuration

  <Expandable title="Properties">
    <ParamField path="fileName" type="string">
      Filename for download
    </ParamField>

    <ParamField path="label" type="string">
      Button text
    </ParamField>

    <ParamField path="component" type="React.Component">
      Custom button component
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="submit" type="object">
  Submit button configuration

  <Expandable title="Properties">
    <ParamField path="label" type="string">
      Button text
    </ParamField>

    <ParamField path="component" type="React.Component">
      Custom button component
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="onDownload" type="function">
  Handle download action

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

<ParamField path="onStateChange" type="function">
  Monitor state changes

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

<ParamField path="onFieldChange" type="function">
  Track field changes

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

<ParamField path="onFieldsDiscovered" type="function">
  Called when document fields are found

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

<ParamField path="onZoomChange" type="function">
  Called when zoom level changes

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

<ParamField path="telemetry" type="object">
  Telemetry configuration. Enabled by default with `source: 'esign'` metadata. See [Telemetry](/resources/telemetry) for details.

  <Expandable title="properties">
    <ParamField path="enabled" type="boolean" default="true">
      Enable or disable telemetry
    </ParamField>

    <ParamField path="metadata" type="Record<string, any>">
      Custom metadata merged with the default `{ source: 'esign' }`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="licenseKey" type="string">
  License key for SuperDoc. Passed directly to the underlying SuperDoc instance.
</ParamField>

<ParamField path="isDisabled" type="boolean">
  Disable all interactions
</ParamField>

<ParamField path="className" type="string">
  CSS class for container
</ParamField>

<ParamField path="style" type="React.CSSProperties">
  Inline styles for container
</ParamField>

<ParamField path="documentHeight" type="string">
  Height of document viewer (default: `'600px'`)
</ParamField>

## 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.</Warning>

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