> For the complete documentation index, see [llms.txt](https://docs.toolkit.equs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toolkit.equs.ai/standards/embedded-ui/overview.md).

# Overview

A front-end library for the Holder-facing parts of Issuance, Presentation and the Web Wallet.

Embed UI is a front-end library that renders the Holder-facing part of a journey inside your own site: the wallet picker, the QR code or deep link, `tx_code` entry, the presentation overview, and the Web Wallet itself. Its screens open in an `iframe` over your page.

### What it covers 🧩

| Journey                   | Start it with               | Guide                                                                                                                         |
| ------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Issuance                  | `issueVC`                   | The **API + Embed UI** method in [Issuance Flow 1](/standards/issuance/flow-1.md) and [Flow 3](/standards/issuance/flow-3.md) |
| Presentation              | `presentVCs`                | [Presentation, Method 1: Embed UI + API](/standards/presentation/flows-1-and-2/embed-ui-and-api.md)                           |
| Agent authorization (AP2) | `presentVCs`                | [AP2, Method 1: Embed UI + API](/standards/agentic/ap2/flow-1/embed-ui-and-api.md)                                            |
| Web Wallet                | Web components or `viewVCs` | [Embedding Web Wallet](/standards/embedded-ui/embedding-web-wallet.md)                                                        |
| Decryption                | `decryptPayload`            | [Decrypt Payload (Embed UI)](/standards/crypto/decrypt-payload-embed-ui.md)                                                   |

{% hint style="info" %}
The Web Wallet, AP2 and Decryption rows all need the Web Wallet, which is off by default and available on request. 
{% endhint %}

### Install 📦

Embed UI is published on npm as [`@equs-ai/dtk-embedded-ui`](https://www.npmjs.com/package/@equs-ai/dtk-embedded-ui). Add it to your front end:

```bash
npm install @equs-ai/dtk-embedded-ui
```

Everything on these pages is imported from it.

### Initialize 🚀

Call `initEmbeddedUi` once, before anything else, typically when your app starts.

```javascript
import { initEmbeddedUi } from '@equs-ai/dtk-embedded-ui'

initEmbeddedUi({
  tenant: 'your-tenant-slug',
  enableWebComponents: true,
})
```

| Option                | Required | Description                                                                                                                                                                   |
| --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tenant`              | Yes      | Your tenant slug. It scopes everything Embed UI loads to you: the Web Wallet, your branding and your identity provider                                                        |
| `region`              | No       | Which regional EQUS deployment Embed UI loads from: `'us'` or `'eu'`. Default `'us'`. `webWalletOrigin` and `embedUiSsiOrigin` override it                                    |
| `enableWebComponents` | No       | Set to `true` to use the [Web Wallet components](/standards/embedded-ui/embedding-web-wallet.md), or to sign the User in to the Web Wallet before opening it. Default `false` |
| `webWalletOrigin`     | No       | Load the Web Wallet from a different origin. Defaults to the EQUS-hosted one for your `region`                                                                                |
| `embedUiSsiOrigin`    | No       | Load Embed UI's own screens, such as the wallet picker, from a different origin. Defaults to the EQUS-hosted one for your `region`                                            |

### Clean up 🧹

Call `cleanUpEmbeddedUi` when your app unmounts. It cancels any journey in progress, closes Embed UI's iframes and removes its listeners.

```javascript
import { initEmbeddedUi, cleanUpEmbeddedUi } from '@equs-ai/dtk-embedded-ui'

// React
useEffect(() => {
  initEmbeddedUi({ tenant: 'your-tenant-slug' })
  return cleanUpEmbeddedUi
}, [])
```

To cancel a single journey (say the Holder navigates away mid-flow) without tearing down the rest, each has its own clean-up function. `cleanUpEmbeddedUi` calls all of them for you.

| Function                | Cancels                                    |
| ----------------------- | ------------------------------------------ |
| `cleanUpIssueVC`        | An Issuance started with `issueVC`         |
| `cleanUpPresentVCs`     | A Presentation started with `presentVCs`   |
| `cleanUpViewVCs`        | A pending `viewVCs`, including its sign-in |
| `cleanUpDecryptPayload` | A decryption started with `decryptPayload` |

### Styling 🎨

Everything Embed UI shows is rendered in an `iframe` you can position and style. See [Styles and Branding](/standards/embedded-ui/styles-and-branding.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.toolkit.equs.ai/standards/embedded-ui/overview.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.