@aoexl/sign-react

React integration for the Aoexl Sign PDF eSignature SDK.

Provides a drop-in <AoexlSign> component and two hooks — useAoexlSign (headless) and usePdfExport — for building fully custom signing flows.

Installation

npm install @aoexl/sign-react @aoexl/sign
# peer deps
npm install react react-dom

Quick start — component

import { AoexlSign } from '@aoexl/sign-react'

export default function SignPage() {
  return (
    <AoexlSign
      licenseKey="pk_live_xxxxxxxxxxxx"
      pdfUrl="https://your-server.com/contract.pdf"
      mode="sign"
      signers={[{ name: 'Jane Doe', email: '[email protected]', role: 'signer' }]}
      onComplete={({ signedPdfBytes, fields }) => {
        console.log('Signing complete', fields)
        // upload signedPdfBytes to your server
      }}
      onError={(err) => console.error('Signing error', err)}
      style={{ height: 700 }}
    />
  )
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | licenseKey | string | — | Required. Your Aoexl license key. | | pdfUrl | string | — | URL of the PDF to load. | | pdfData | Uint8Array \| Blob \| string | — | Raw PDF bytes or data-URL (alternative to pdfUrl). | | mode | 'prepare' \| 'sign' \| 'view' \| 'full' | 'sign' | Viewer mode. | | signers | Signer[] | [] | Signer definitions (id, name, email, role). | | fields | Field[] | [] | Pre-placed field definitions. | | theme | Theme | — | Color and layout overrides. | | ui | UIConfig | — | Hide buttons or tabs using hide: []. | | config | ViewerConfig | — | Behavioural flags like autoJumpNextSign. | | onComplete | (result: CompleteResult) => void | — | Fired when signing is finished. | | onSave | (result: CompleteResult) => void | — | Fired on every manual save/download. | | onDocumentLoaded | ({ pageCount }) => void | — | Fired after the PDF is parsed. | | onAllSigned | ({ fields }) => void | — | Fired when the last required field is filled. |

API Reference (Ref)

When using a ref with <AoexlSign> or the destroy method from useAoexlSign, you have access to:

• savePdf(options?): Trigger a browser download.
• getPdfBytes(): Returns the final PDF as a Uint8Array.
• flattenPdf(): Returns a flattened version of the PDF.
• setScale(number): Change zoom level dynamically.
• zoomIn() / zoomOut(): Standard zoom controls.
• fitWidth() / fitPage(): Responsive scaling tools.

Headless hook — useAoexlSign

Use this when you need full control over the container or want to show your own loading UI.

import { useAoexlSign } from '@aoexl/sign-react'

export default function CustomSignPage() {
  const { ref, status, error, fields, destroy } = useAoexlSign({
    licenseKey: 'pk_live_xxxxxxxxxxxx',
    pdfUrl: 'https://your-server.com/contract.pdf',
    mode: 'sign',
    signers: [{ name: 'Jane Doe', email: '[email protected]' }],
    onComplete: ({ signedPdfBytes }) => {
      // handle completion
    },
    onError: (err) => console.error(err),
  })

  return (
    <div>
      {status === 'loading' && <p>Loading PDF viewer…</p>}
      {status === 'error'   && <p style={{ color: 'red' }}>{error}</p>}
      <div
        ref={ref}
        style={{ height: 700, border: '1px solid #e2e8f0', borderRadius: 8 }}
      />
    </div>
  )
}

Return values

| Value | Type | Description | |-------|------|-------------| | ref | RefObject<HTMLDivElement> | Attach to your container element. | | status | 'idle' \| 'loading' \| 'ready' \| 'error' | Current lifecycle state. | | error | string \| null | Error message when status === 'error'. | | fields | Field[] | Current field array (updated after onComplete). | | destroy | () => void | Manually unmount the viewer. |

usePdfExport

Download a signed PDF to the user's device.

import { useAoexlSign, usePdfExport } from '@aoexl/sign-react'

export default function SignAndDownload() {
  const { download, downloading } = usePdfExport()

  const { ref } = useAoexlSign({
    licenseKey: 'pk_live_xxxxxxxxxxxx',
    pdfUrl: 'https://your-server.com/contract.pdf',
    onComplete: ({ signedPdfBytes }) => {
      if (signedPdfBytes) {
        download(signedPdfBytes, 'signed-contract.pdf')
      }
    },
  })

  return (
    <>
      {downloading && <p>Preparing download…</p>}
      <div ref={ref} style={{ height: 700 }} />
    </>
  )
}

Return values

| Value | Type | Description | |-------|------|-------------| | download | (bytes, filename?) => void | Trigger a browser file download. | | toBase64 | (bytes) => string | Convert bytes to a base64 string. | | toBlob | (bytes) => Blob | Wrap bytes in a PDF Blob. | | downloading | boolean | True while the file is being prepared. | | error | string \| null | Set if the download threw. |

TypeScript

All types are exported from the package entry point:

import type {
  UseAoexlSignOptions,
  UseAoexlSignResult,
  UsePdfExportResult,
  Field,
  Signer,
  CompleteResult,
  Theme,
} from '@aoexl/sign-react'

Building

npm run build   # outputs dist/index.js (ESM) + dist/index.cjs (CJS)

License

UNLICENSED — contact Aoexl for a commercial license.