Integrate Legalesign Signer into Your Website

The Legalesign Signer is a platform-agnostic web component that provides a complete and seamless document signing experience from within your own app. It works with vanilla HTML, React, Vue, Angular, or any web framework.

Embed this component wherever your users need to sign documents — inside a CRM, client portal, or any internal application that renders HTML.

Installation

Install via a package manager:

npm install legalesign-signer
# or
pnpm add legalesign-signer

Or load directly from the CDN (no install required):

<script type="module" src="https://cdn.legalesign.io/signer/latest/ls-signer.esm.js"></script>

Basic Integration

Vanilla HTML/JavaScript

<ls-signer
  recipient-id="abc123"
  private-key="key"
  session-id="session"
  api-base-url="https://app1.legalesign.com"
></ls-signer>

<script>
  const signer = document.querySelector('ls-signer');
  signer.addEventListener('signingSuccess', (e) => console.log('Signed:', e.detail));
  signer.addEventListener('signingFail', (e) => console.error('Failed:', e.detail));
</script>

React

import { useEffect, useState } from 'react';
import { LsSigner } from 'legalesign-signer/react';
import 'legalesign-signer/react.css';

function SigningPage() {
  const [signerData, setSignerData] = useState(null);

  useEffect(() => {
    fetch('/api/signer-token')
      .then(res => res.json())
      .then(setSignerData);
  }, []);

  if (!signerData) return <p>Loading...</p>;

  return (
    <LsSigner
      recipientId={signerData.recipientId}
      privateKey={signerData.token}
      sessionId={signerData.sessionId}
      onSuccess={({ documentId }) => console.log('Signed:', documentId)}
      onFail={({ error }) => console.error('Failed:', error)}
    />
  );
}

React requires react and react-dom (v18 or v19) as peer dependencies.

Vue

Add the script tag to your index.html:

<script type="module" src="https://cdn.legalesign.io/signer/latest/ls-signer.esm.js"></script>

Use in your component:

<template>
  <ls-signer
    :recipient-id="recipientId"
    :private-key="privateKey"
    :session-id="sessionId"
    @signingSuccess="handleSuccess"
    @signingFail="handleFail"
  />
</template>

astuce

If using Vue with Vite, add isCustomElement: (tag) => tag.startsWith('ls-') to your Vue plugin config to suppress unknown element warnings.

Authentication

The signer component requires a short-lived token from your backend. Call generateComponentToken with component: LS_SIGNER and either a recipientId or sessionId in the signer scope (provide one, not both). The mutation returns the token and sessionId needed by the component.

See Widget Authorization for the full server-side token flow.

Server-side token request (Node.js)

Using recipientId (most common — use when you know the recipient but don't yet have a session):

const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.LEGALESIGN_API_KEY}`,
  },
  body: JSON.stringify({
    query: `mutation MintSignerToken($input: GenerateComponentTokenInput!) {
      generateComponentToken(input: $input) {
        token
        tokenType
        sessionId
        expiresIn
        expiresAt
      }
    }`,
    variables: {
      input: {
        component: 'LS_SIGNER',
        signer: { recipientId: '<recipient-id>' }
      }
    }
  })
});

const { data } = await response.json();
const { token, sessionId } = data.generateComponentToken;

Alternatively, if you already have a sessionId from a previous call:

variables: {
  input: {
    component: 'LS_SIGNER',
    signer: { sessionId: '<session-id>' }
  }
}

Pass token as private-key and sessionId as session-id to the component.

Required Attributes

Attribute	Type	Description
recipient-id	string	Recipient identifier (base64, rec prefix, or UUID)
private-key	string	Token returned by generateComponentToken
session-id	string	Session ID returned by generateComponentToken

Optional Attributes

Attribute	Type	Default	Description
api-base-url	string	https://app1.legalesign.com	API base URL
colour	string	blue	Theme colour name (see Theming)

Events

Event	Detail	Description
signingSuccess	{ documentId, recipientId }	Emitted when signing completes
signingFail	{ error, documentId?, recipientId }	Emitted on signing failure

React Props

The React component uses camelCase props and callback props instead of DOM events:

Prop	Type	Required	Description
recipientId	string	✅	Recipient identifier
privateKey	string	✅	Private key from session API
sessionId	string	✅	Session identifier
apiBaseUrl	string	❌	API base URL
colour	LsSignerColour	❌	Theme colour
onSuccess	(data: { documentId: string; recipientId: string }) => void	❌	Called on successful signing
onFail	(data: { error: string; documentId?: string; recipientId: string }) => void	❌	Called on signing failure

Theming

Set a colour theme with the colour prop. All shades are derived automatically.

Available Colours

pink · blue · purple · indigo · teal · green · lightblue · burnt · aubergine · red · yellow · cyan · lime · trueGreen

Omit the prop for the default blue.

<ls-signer colour="pink" ...></ls-signer>

<LsSigner colour="pink" ... />

The colour prop sets a data-ls-theme attribute on the component root. CSS custom properties define a 10–100 shade scale for each colour:

Shade	Usage
10	Light backgrounds, subtle fills
20	Subtle borders
30	Focus rings
60	Primary colour (buttons, links, active states)
70	Hover state
80	Dark/strong accents

Complete Example

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document Signing</title>
    <script type="module" src="https://cdn.legalesign.io/signer/latest/ls-signer.esm.js"></script>
  </head>
  <body>
    <ls-signer
      recipient-id="abc123"
      private-key="key"
      session-id="session"
      colour="teal"
    ></ls-signer>

    <script>
      const signer = document.querySelector('ls-signer');

      signer.addEventListener('signingSuccess', (event) => {
        console.log('Document signed:', event.detail.documentId);
        window.location.href = '/thank-you';
      });

      signer.addEventListener('signingFail', (event) => {
        console.error('Signing failed:', event.detail.error);
      });
    </script>
  </body>
</html>

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Mobile browsers (iOS Safari, Chrome Mobile)

Resources

• NPM Package
• Widget Authorization
• GraphQL API Documentation
• Support