iframe
Embed the signing experience directly in your application using an iframe.
iframes are not recommended
Embedding via iframe is not recommended. We strongly recommend using the official SDKs instead.
Basic iframe Embedding
<iframe
src="https://app.documenso.com/embed/sign/abc123xyz"
width="100%"
height="800"
frameborder="0"
allow="clipboard-write"
></iframe>Use the correct embed URL
The URL you embed depends on the embed mode you’re using (for example direct links vs sign-token embeds). Use the embed URL provided by Documenso for your flow.
iframe Customization
You can customize the embedded signing experience by passing encoded options in the iframe URL fragment (everything
after #).
Documenso expects the fragment to be base64 of:
encodeURIComponent(JSON.stringify(options))
Supported options
| Option | Type | Description |
|---|---|---|
name | string | Prefill signer name. |
email | string | Prefill signer email. |
lockName | boolean | Lock the name field (prevents editing). |
lockEmail | boolean | Lock the email field (prevents editing). |
language | string | Force the embed language (e.g. en). |
darkModeDisabled | boolean | Disable dark mode behavior. |
allowDocumentRejection | boolean | Allow or disallow document rejection. |
css | string | Inject custom CSS into the embed. |
cssVars | object | Override embed CSS variables (see the CSS Variables page). |
Example
const buildEmbedSrc = (host: string, token: string) => {
const options = {
name: 'Ada Lovelace',
email: 'ada@example.com',
lockName: true,
lockEmail: true,
language: 'en',
darkModeDisabled: false,
allowDocumentRejection: true,
css: ':root { --radius: 12px; }',
cssVars: {},
};
const encodedOptions = btoa(encodeURIComponent(JSON.stringify(options)));
return `${new URL(`/embed/sign/${token}`, host).toString()}#${encodedOptions}`;
};A complete example can be found in the Embeds repository.
Query parameters
A small number of options are read server side and are therefore passed as regular query parameters rather than in the fragment.
| Parameter | Applies to | Description |
|---|---|---|
clientUserId | /embed/sign/:token | Opaque signer identifier used to prefill and persist the signer's signature across embeds. Platform Plan. See Persisting Signatures. |
externalId | /embed/direct/:token | Your reference ID, stored with the document created from the direct template. |
const src = new URL(`/embed/sign/${token}`, host);
src.searchParams.set('clientUserId', 'usr_8f2c1b4e');
return `${src.toString()}#${encodedOptions}`;Keep identifiers opaque
Query parameters are part of the HTTP request and will appear in Documenso's request logs. Never put an email address
or other personally identifiable information in clientUserId; use an opaque ID instead.
Why use the URL fragment?
The fragment is not sent to the server as part of the HTTP request, but it is available to the embedded app in the browser. This makes it a convenient way to pass client-side configuration without changing the base embed URL.