Skip to Content
Embedding

Embed signing with JavaScript

Embed the signing page in any web page with the @sajn/embed-js function API or Web Component

In this guide, you embed the sajn signing page in a web page with the @sajn/embed-js package, through its function API or its Web Component. The @sajn/embed-js package provides two ways to embed the signing experience: a function API and a Web Component.

Before you begin

  • Turn on embedding for your organization and add your domain to the allowlist. For more information, see Embedded signing.
  • On your server, create the document and read the party's token from the signingUrl that GET /api/v1/documents/DOCUMENT_ID/parties/PARTY_ID returns. For the steps, see Embed the signing page. Never call the sajn API from the browser, because the request needs your API key.

Installation

npm

npm install @sajn/embed-js

CDN

For projects without a build step, use the UMD bundle:

<script src="https://unpkg.com/@sajn/embed-js"></script>

This exposes the sajn global object with all exports.

Use the function API

The embedSignDocument function creates an iframe and handles all communication with the embedded signing interface.

Import

import { embedSignDocument } from '@sajn/embed-js';

Or with CDN:

const { embedSignDocument } = sajn;

Options

interface EmbedSignDocumentOptions {
  // Required
  element: HTMLElement | string;  // Target element or CSS selector
  documentId: string;             // Document ID
  token: string;                  // The party's token

  // Optional
  host?: string;                  // Default: 'https://app.sajn.se'
  language?: 'sv' | 'en' | 'no' | 'da' | 'fi' | 'de' | 'is' | 'es' | 'fr' | 'it';
  className?: string;             // CSS class for iframe
  cssVars?: CssVars & Record<string, string>;
  allowDocumentRejection?: boolean;
  showScrollIndicator?: boolean;  // Default: true
  signatureInputModes?: ('draw' | 'type' | 'upload')[];  // Default: all
  showDocumentId?: boolean;  // Default: true
  additionalProps?: Record<string, string | number | boolean>;

  // Callbacks
  onDocumentReady?: () => void;
  onSignerCompleted?: (data: SignerCompletedData) => void;
  onVariablesSubmitted?: (data: VariablesSubmittedData) => void;
  onSignerRejected?: (data: SignerRejectedData) => void;
  onDocumentError?: (data: { code: string; message: string }) => void;
}

Return value

interface EmbedSignDocumentInstance {
  iframe: HTMLIFrameElement;  // The created iframe element
  destroy: () => void;        // Cleanup function
}

Example

import { embedSignDocument } from '@sajn/embed-js';

const instance = embedSignDocument({
  element: '#signing-container',
  documentId: 'cm4k2x9p10001abcd1234efgh',
  token: 'K7xq2m9VbN4pR8sT1wY6zA3c',
  cssVars: {
    primary: '#2563eb',
    background: '#ffffff',
  },
  allowDocumentRejection: true,
  onDocumentReady: () => {
    console.log('Signing interface loaded');
  },
  onSignerCompleted: (data) => {
    console.log('Document signed!', data);
    // Redirect or show success message
  },
  onSignerRejected: (data) => {
    console.log('Document rejected:', data.reason);
  },
  onDocumentError: (error) => {
    console.error('Error:', error.code, error.message);
  },
});

// Later: cleanup when done
instance.destroy();

Use the Web Component

The package also exports a custom element <sajn-sign-document> that auto-registers when imported.

Import

import '@sajn/embed-js';

Or with CDN, the component is automatically registered.

Attributes

AttributeTypeRequiredDescription
document-idstringYesDocument ID
tokenstringYesThe party's token
hoststringNoCustom host URL
languagestringNoUI language (sv, en, no, da, fi, de, is, es, fr, it)
class-namestringNoCSS class for iframe
allow-document-rejectionbooleanNoEnable rejection
show-scroll-indicatorbooleanNoShow scroll indicator (default: true)
signature-input-modesstringNoComma-separated list of draw, type, upload (default: all)
show-document-idbooleanNoShow the document ID under the sign button (default: true)

Events

The Web Component dispatches standard CustomEvents that you can listen to:

EventDetail
document-readyundefined
signer-completedSignerCompletedData
variables-submittedVariablesSubmittedData
signer-rejectedSignerRejectedData
document-errorDocumentErrorData

Example

<div id="signing-wrapper" style="width: 100%; height: 600px;">
  <sajn-sign-document
    document-id="cm4k2x9p10001abcd1234efgh"
    token="K7xq2m9VbN4pR8sT1wY6zA3c"
    allow-document-rejection
  ></sajn-sign-document>
</div>

<script type="module">
  import '@sajn/embed-js';

  const signDocument = document.querySelector('sajn-sign-document');

  signDocument.addEventListener('document-ready', () => {
    console.log('Ready');
  });

  signDocument.addEventListener('signer-completed', (event) => {
    console.log('Signed!', event.detail);
  });

  signDocument.addEventListener('signer-rejected', (event) => {
    console.log('Rejected:', event.detail.reason);
  });

  signDocument.addEventListener('document-error', (event) => {
    console.error('Error:', event.detail.code);
  });
</script>

Use the CDN bundle

Complete HTML page using the UMD bundle:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Sign Document</title>
  <style>
    #signing-container {
      width: 100%;
      height: 100vh;
    }
  </style>
</head>
<body>
  <div id="signing-container"></div>

  <script src="https://unpkg.com/@sajn/embed-js"></script>
  <script>
    const { embedSignDocument } = sajn;

    const instance = embedSignDocument({
      element: '#signing-container',
      documentId: 'cm4k2x9p10001abcd1234efgh',
      token: 'K7xq2m9VbN4pR8sT1wY6zA3c',
      onSignerCompleted: (data) => {
        alert('Document signed successfully!');
        window.location.href = '/thank-you';
      },
      onDocumentError: (error) => {
        alert('An error occurred: ' + error.message);
      },
    });
  </script>
</body>
</html>

TypeScript types

The package exports all types for TypeScript users:

import type {
  EmbedSignDocumentOptions,
  EmbedSignDocumentInstance,
  EmbedViewDocumentOptions,
  EmbedViewDocumentInstance,
  SignerCompletedData,
  SignerRejectedData,
  SignatureInputMode,
  Language,
  CssVars,
} from '@sajn/embed-js';

View a signed document

The package also includes embedViewDocument for displaying signed documents in read-only mode.

Use the function API

import { embedViewDocument } from '@sajn/embed-js';

Or with CDN:

const { embedViewDocument } = sajn;

Options

interface EmbedViewDocumentOptions {
  // Required
  element: HTMLElement | string;  // Target element or CSS selector
  documentId: string;             // Document ID
  token: string;                  // The party's token, the same as for signing

  // Optional
  host?: string;                  // Default: 'https://app.sajn.se'
  language?: 'sv' | 'en' | 'no' | 'da' | 'fi' | 'de' | 'is' | 'es' | 'fr' | 'it';
  className?: string;             // CSS class for iframe
  cssVars?: CssVars & Record<string, string>;
  showScrollIndicator?: boolean;  // Default: true
  additionalProps?: Record<string, string | number | boolean>;

  // Callbacks
  onDocumentReady?: () => void;
  onDocumentError?: (data: { code: string; message: string }) => void;
}

Example

import { embedViewDocument } from '@sajn/embed-js';

const instance = embedViewDocument({
  element: '#viewer-container',
  documentId: 'cm4k2x9p10001abcd1234efgh',
  token: 'K7xq2m9VbN4pR8sT1wY6zA3c',
  cssVars: {
    primary: '#2563eb',
    background: '#ffffff',
  },
  onDocumentReady: () => {
    console.log('Document loaded');
  },
  onDocumentError: (error) => {
    console.error('Error:', error.code, error.message);
  },
});

// Later: cleanup when done
instance.destroy();

Use the Web Component

The package also exports a custom element <sajn-view-document>:

import '@sajn/embed-js';
<div id="viewer-wrapper" style="width: 100%; height: 600px;">
  <sajn-view-document
    document-id="cm4k2x9p10001abcd1234efgh"
    token="K7xq2m9VbN4pR8sT1wY6zA3c"
  ></sajn-view-document>
</div>

<script type="module">
  import '@sajn/embed-js';

  const viewDocument = document.querySelector('sajn-view-document');

  viewDocument.addEventListener('document-ready', () => {
    console.log('Ready');
  });

  viewDocument.addEventListener('document-error', (event) => {
    console.error('Error:', event.detail.code);
  });
</script>

Next steps

Embedded signing

See the shared options, events, and security model.

Embed signing in your app

Run the whole flow from server to iframe.

Was this page helpful?

Last updated on