---
title: "Set Up an Embedded UI Module"
slug: "set-up-an-embedded-ui-module"
tags: ["embedded-ui"]
updated: 2026-09-14T19:10:15Z
published: 2026-09-14T19:10:15Z
canonical: "docs.unqork.io/set-up-an-embedded-ui-module"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unqork.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up an Embedded UI Module

This guide walks through embedding a single Unqork module in an external web page using the Embedded UI. By the end, a working module renders inside the host page without redirecting the end-user or affecting the host page's styles.

## Prerequisites

Complete these steps before beginning:

- An Unqork environment with the Embedded UI feature enabled. The `embedded.js` script returns a 404 error if the feature is not active on the environment.
- The host page domain added as a CORS exception in **Environment Administration > Cross-Origin Resource Sharing (CORS)**. Browsers block cross-origin API requests by default. Without this exception, the runtime cannot reach the Unqork API from the host page.
- A published module with a known module ID. The runtime fetches the module definition by its 24-character MongoDB ObjectId. Unpublished modules are not accessible.

## Step 1: Add the Embedded Script

Add a single `<script>` tag to the host page pointing to the Unqork environment's `embedded.js` endpoint. Loading this script creates `window.unqork`, the entry point for all runtime API calls. Without it, the runtime object does not exist and no modules can mount.

```plaintext
<script src="https://your-environment.unqork.io/embedded.js"></script>
```

> [!NOTE]
> The script must load after the DOM is ready. Place the script tag at the end of `&lt;body&gt;` or use the `defer` attribute.

## Step 2: Add a Mount Target

Add an element to the host page where the module will render. The runtime registers it as a Shadow DOM web component, keeping styles isolated between the module and the host page. The tag name can be any hyphenated name not already registered as a custom element.

```plaintext
<unqork-app></unqork-app>
```

## Step 3: Initialize and Mount

Write a script that initializes the runtime and mounts the module. Always call `initialize()` before `mountModule()`. The runtime must complete its internal setup before it can load a module. Calling `mountModule()` first returns an error.

```plaintext
<script>
  (async () => {
    const runtime = window.unqork.runtimes.default
    await runtime.initialize()
    await runtime.mountModule({
      moduleId: '696f9c76f9325e1f580152c7',
      target: 'unqork-app'
    })
  })()
</script>
```

| Parameter | Description |
| --- | --- |
| `moduleId` | The MongoDB ObjectId of the module to embed. |
| `target` | The custom element tag name (for example, `unqork-app`) where the module renders. |

## Step 4: Add Error Handling (Optional)

The embedded runtime does not surface errors to the host page. It dispatches them as custom DOM events instead. Without a listener, errors occur silently and the module stops working with no explanation.

```plaintext
<script>
  window.addEventListener('unqork-embed-error', (event) => {
    console.error('Embed error:', event.detail.type, event.detail.message)
  })
</script>
```

## Step 5: Add Authentication (If Required)

Modules with access controls reject unauthenticated requests with a 401 or 403 error. Checking the authentication status before mounting prevents a visible error state when the module first loads.

```plaintext
<script>
  (async () => {
    const runtime = window.unqork.runtimes.default
    await runtime.initialize()

    if (!(await runtime.isAuthenticated())) {
      await runtime.authenticateAnonymous({ moduleId: 'abc123' })
    }

    await runtime.mountModule({ moduleId: 'abc123', target: 'unqork-app' })
  })()
</script>
```

## Complete Example

The following is a minimal but complete host page that embeds a module with error handling.

```plaintext
<!DOCTYPE html>
<html>
<head>
  <title>My App with Unqork Module</title>
</head>
<body>
  <h1>My Application</h1>
  <unqork-app></unqork-app>
  <a href="https://google.com" target="_blank">External Link (still works)</a>

  <script src="https://my-unqork-env.unqork.io/embedded.js"></script>
  <script>
    window.addEventListener('unqork-embed-error', (event) => {
      console.error('Embed error:', event.detail.type, event.detail.message)
    })

    ;(async () => {
      const runtime = window.unqork.runtimes.default
      await runtime.initialize()
      await runtime.mountModule({
        moduleId: '696f9c76f9325e1f580152c7',
        target: 'unqork-app'
      })
    })()
  </script>
</body>
</html>
```

---

**Changelog**

| Date | Change |
| --- | --- |
| 2026-09-11 | Fixed broken See Also links; updated In-Depth Setup reference (EN-8097). |
| 2026-06-08 | Added "why" context to Prerequisites, Steps 1–5. |
| 2026-04-21 | Initial publication. |

The UI (user interface) is a device's end-user interaction and communication point. It can include display screens, keyboards, and mouse. It is also how a user interacts with your application.

Rendering is the process of loading components and displaying the final result on the front-end screen.

End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.

A functionality of a software. For example, Copy and Paste is a feature of a computer's operating system.

Cross-Origin Resource Sharing (CORS) lets you control access to resources located outside a given domain.

APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services.

An API endpoint is the location where an API receives requests for a specific resource on its server. It's the point of contact between an API client and an API server, and is usually a uniform resource locator (URL) that provides the location of the resource.

A definition

An object is a type of data structure that represents a single, self-contained entity that acts as a container for the characteristics of that entity.

The Document Object Model (DOM) is the data representation of objects that form the structure and content of a document on the web. The DOM represents the page.

Rendering is the process of loading components and displaying the final result on the front-end screen.

The Shadow DOM is a web standard that allows you to create encapsulated, hidden DOM subtrees for your web components. It provides a way to scope CSS styles and JavaScript behavior within a component, preventing them from leaking out and interfering with the rest of the page.