> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# Docusign JS for embedded signing reference

> See details about Docusign JS methods used for embedded signing.

You can use the Docusign JS JavaScript library to:

* Implement [Embedded signing](/docs/esign-rest-api/esign101/concepts/embedding/embedded-signing) with focused view, focused view/Click to Agree, and classic signing sessions.
* Render web form instance URLs for the Docusign [Web Forms API](/docs/web-forms-api/plan-integration/render-instances#use-docusign-js-to-render-web-form-instance-urls).

This topic focuses on using Docusign JS for embedded signing. See [Web Forms API](/docs/web-forms-api/plan-integration/render-instances#use-docusign-js-to-render-web-form-instance-urls) when using it with the Web Forms API. The library can be used for both purposes on the same web page.

## 1. Install Docusign JS

Add the development or production version of Docusign JS to your web page:

* If your app uses the **Development environment**:
  `<script src="https://js-d.docusign.com/bundle.js"></script>`
* If your app uses the **Production environment**:
  `<script src="https://js.docusign.com/bundle.js"></script>`

**Note**: Do not make a local copy of `bundle.js`, it must match the platform version.

## 2. Add a container element to your DOM

When the Docusign JS mount method is called, it will add an iframe to the DOM element you use as an argument for the method. When the `sessionEnd` event is raised, the library will delete the iframe.

Add an empty block element (such as a `div`) to your DOM to hold the iframe. You must set the block element’s `width` and `height`. You can use `@media` CSS to change the `div`’s width based on the overall screen’s width. Bootstrap and other layout systems can also be used.

**`Example container element`**

```html title="Example container element"
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Signing</title>
    <style>
      html, body {
        padding: 0;
        margin: 0;
        font: 13px Helvetica, Arial, sans-serif;}
        /* container styles */
        @media (max-width: 768px){
          .docusign-agreement-container {width: 50%}}
        @media (min-width: 769px) (max-width: 1024px) {
          .docusign-agreement-container {width: 70%}}
        @media (min-width: 1025px) {
          .docusign-agreement-container {width: 100%}}
    </style>
  </head>
  <body>
    <header><h1> Demo</h1></header>
    <div class="docusign-agreement-container" id="docusignContainer"></div>
  </body>
</html>
```

## 3. Call EnvelopeViews:createRecipient

Call the [EnvelopeViews:createRecipient](/docs/esign-rest-api/reference/envelopes/envelopeviews/createrecipient) API method and provide values for the [frameAncestors](/docs/esign-rest-api/reference/envelopes/envelopeviews/createrecipient#schema__recipientviewrequest_frameancestors) and [messageOrigins](/docs/esign-rest-api/reference/envelopes/envelopeviews/createrecipient#schema__recipientviewrequest_messageorigins) attributes:

* The [frameAncestors](/docs/esign-rest-api/reference/envelopes/envelopeviews/createrecipient#schema__recipientviewrequest_frameancestors) attribute is an array of HTTP [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin) strings, not including anything after the hostname or port. Include the `https://apps-d.docusign.com` origin for the developer environment or `https://apps.docusign.com` for production. Include additional  origins for your app’s ancestor origins that will embed the signing session. Origins must use `https` rather than `http`, with the exception of for `localhost`. The `localhost` origin can’t be used in production.

  **Note:** `frameAncestors` has a limit of 500 characters (for all URLs combined).

  **Examples**:

  ```json
  ["https://apps-d.docusign.com", "http://localhost"] # default port
  ["https://apps-d.docusign.com", "http://localhost:8080"] # specific port
  ["https://apps.docusign.com", "https://app1.example.com",
  	"http://app1frame.example.com"] # production
  ```
* The [messageOrigins](/docs/esign-rest-api/reference/envelopes/envelopeviews/createrecipient#schema__recipientviewrequest_messageorigins) attribute is an array of HTTP [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin) strings. The array must have one member:

  * `["https://apps-d.docusign.com"] # demo`
  * `["https://apps.docusign.com"] # production`
* The [returnUrl](/docs/esign-rest-api/reference/envelopes/envelopeviews/createrecipient#schema__recipientviewrequest_returnurl) attribute must be set, but will not be used.

All other attributes should be set as usual.

The [EnvelopeViews:createRecipient](/docs/esign-rest-api/reference/envelopes/envelopeviews/createrecipient) API method’s [url](/docs/esign-rest-api/reference/envelopes/envelopeviews/createrecipient#schema_201_envelopeviews_envelopeviews_url) response is used in the browser with Docusign JS. If you call `createRecipient` on the server, return the url to your browser page.

The `window.loadDocuSign(``integration_key``) RETURNS` `Promise` resolves to a Docusign object, and is called first to obtain the Docusign object.

**Performance tip**: This method can be called asynchronously before it is needed to create a signing session.

The `integration_key` argument is a string that contains your application’s integration key (client ID). Client IDs are not secrets.

### Signing method

The Docusign object includes the `signing` method:

`signing(SigningConfiguration)` `RETURNS Signing object`

The `signing` method creates the embedded signing session. It takes as a parameter a `SigningConfiguration` object to control the signing session’s format and style attributes. The returned `Signing` object represents the signing session that will be displayed. See [Signing object methods](/docs/esign-rest-api/esign101/concepts/embedding/docusign-js-embedded-reference#signing-object-methods) for a list of methods.

#### SigningConfiguration object properties

| Property name   | Type                 | Description                                                                                                                                                                                                                                                                   |
| --------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`           | `string`             | Required. The signing URL response from [EnvelopeViews:createRecipient](/docs/esign-rest-api/reference/envelopes/envelopeviews/createrecipient).                                                                                                                              |
| `displayFormat` | `string`             | Required. The signing session’s UX format. Possible values are:- `"focused"`: Sets the signing session to use focused view or (if the main documents have no tabs) focused view/Click to Agree
- `"default"`: Sets the signing session to use the Docusign classic UX format. |
| `style`         | `StyleObject object` | Optional. A `StyleObject` containing style settings for the signing session.                                                                                                                                                                                                  |

#### StyleObject properties

Some styling options have not yet been implemented for some display formats.

```json
{
 branding: BrandingObject,
 signingNavigationButton: SigningNavigationButtonObject
}
```

The following options are supported for the Docusign JS `StyleObject`:

| Property name                            | Type                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `branding`                               | `BrandingObject`                | A container for objects on which branding style elements can be applied. Currently this consists of the `primaryButton` object.                                                                                                                                                                                                                                                                                                                                                                                                                |
| `primaryButton (sub-object of branding)` | `PrimaryButtonObject`           | Settings for the primary UX button. Properties:- `color`: CSS color value for the text of the button.
- `backgroundColor`: CSS color value for the button itself.                                                                                                                                                                                                                                                                                                                                                                              |
| `signingNavigationButton`                | `SigningNavigationButtonObject` | Optional; specifies position and text for the signing button. Properties:- `finishText`: String with a maximum of 50 characters.
- `position`: Accepts one of these values: `'bottom-left'`, `'bottom-center'`, `'bottom-right'`.                                                                                                                                                                                                                                                                                                              |
| `signingDeclineButton`                   | `signingDeclineButtonObject`    | Optional; specifies if a Decline button will be shown. This option is not available for all display formats.  Properties:- `show`: A boolean value that indicates whether to show a Decline button or not. If `false` (default), do not show a Decline button. If `true`, show a Decline button. See [Decline and Approve tab types](/docs/esign-rest-api/reference/envelopes/enveloperecipienttabs#tab-types) for more information.
- `finishText`**:** String with a maximum of 50 characters that will render on the `signingDeclineButton` |
| `declineModal`                           | `declineModalObject`            | Optional; `show` indicates whether to show a Decline modal or not to require a reason to decline or to decline immediately. Defaults to `false`.                                                                                                                                                                                                                                                                                                                                                                                               |
| `downloadModal`                          | `downloadModalObject`           | Optional; `show` indicates whether to show a download completed document modal after envelope finish. Defaults to `false`.                                                                                                                                                                                                                                                                                                                                                                                                                     |

#### Example SigningConfiguration object

```text
const signingConfiguration = {
    url: recipientViewUrl,
    displayFormat: 'focused',
    style: {
        branding: {
            primaryButton: {
                backgroundColor: 'purple',
                color: 'white'
            }
        },
        signingNavigationButton: {
            finishText: 'Submit',
            position: 'bottom-right'
        },
        signingDeclineButton: {
            show: true, // default value is false
            finishText: 'Decline Button Text'
        },
        declineModal: {
            show: true // default value is false
        },
        downloadModal: {
            show: true // default value is false
        }
    }
}
```

#### Signing object methods

The signing object is used to display the signing session and catch the signing-related events it raises.

| Method name                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mount(containerSelectString)` | Adds, then displays the signing session to the DOM. This is a synchronous method that initiates asynchronous side effects (the signing session is displayed). The ready event is raised when the session has been displayed. The required `containerSelectString` parameter is a CSS selector string that resolves to the container element for the signing session. For example: `"#docusignContainer"`                                                                                                                                                                                                                |
| `on(eventName, cbFunction)`    | The `on` method adds an event listener. - The required `cbFunction` parameter is a function with an **event** argument. - The required `eventName` parameter is a string naming the event. The following events are supported as `eventName` argument values: - `ready`: The signing session has been displayed and is ready for the user - `sessionEnd`: The signing session has ended. There are multiple reasons for this event, for which the `event.sessionEndType` string will be set: `text 'signing_complete' 'cancel' 'decline' 'exception' 'fax_pending' 'session_timeout' 'ttl_expired' 'viewing_complete' ` |

## Use Docusign JS with JavaScript

This example uses the JavaScript [module type](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#module) to enable the [await keyword at the top level](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#top_level_await) of the script.

```text
<style>
    .hide {display: none;}
</style>
...
<script type="module">
    let signingUrl; // the EnvelopeViews:createRecipient response
    let clientId; // your app’s IK
    const signingConfiguration = {
        url: signingUrl,
        displayFormat: 'focused',
        style: // see above for an example
    }
    try {
        const docusign = await window.DocuSign.loadDocuSign(clientId);
        const signing = docusign.signing(signingConfiguration);

        /** Event handlers **/
        signing.on('ready', (event) => {console.log('UI is rendered')});
        signing.on('sessionEnd', (event) => {
            console.log('sessionEnd', event)});
        // Open the signing ceremony
        $(`#main`).addClass("hide"); // JQuery to hide content
        $(`#signing-ceremony`).removeClass("hide"); // Display the container
        signing.mount(`#signing-ceremony`);
    } catch (error) {
        // Any configuration or API limits will be caught here
        console.log ("### Error calling docusign.js");
        console.log (error);
    }
</script>
```