---
title: "Embedded UI Navigation Guards and URL Isolation Reference"
slug: "embedded-ui-navigation-guards-and-url-isolation-reference"
tags: ["embedded-ui", "reference-guides"]
status: "update"
updated: 2026-10-13T18:19:07Z
published: 2026-10-13T18:19:07Z
canonical: "docs.unqork.io/embedded-ui-navigation-guards-and-url-isolation-reference"
---

> ## 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.

# Embedded UI Navigation Guards and URL Isolation Reference

When an Unqork module runs inside Embedded UI, the module and the host page compete for control of the browser's address bar. The module's routing system expects to own the URL and update it as end-users navigate through module screens. Without intervention, those URL changes would push the host page to a different address, breaking the host application's routing and browser history. The navigation guard system resolves this conflict by intercepting URL change attempts from the module and keeping the host page's address bar stable throughout the session.

This reference covers how navigation guards work, how link interception operates, and how Shadow DOM and CSS isolation function in Embedded UI.

## Why Navigation Guards Are Needed

Angular's internal routing system assumes it owns the browser's URL bar. In embedded mode, URL mutations must be suppressed so the host page's address remains unchanged. Without these guards, Angular would change the host page URL every time the embedded module navigates internally, breaking the host application.

## $browser Decorator

The `$browser` service controls how Angular reads and sets the browser URL. In embed mode, this service is modified so URL changes from Angular routing never reach the host page's address bar.

**Field**: `$browser.url()` | **Type**: Angular service decorator

The `$browser` service is decorated during `angular.module('unqorkEmbed').config()`. All SET calls are silently ignored. calls pass through normally.

![Diagram](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261013_181903_31ae31528a8d4efbb979e4038d826f6f.svg?sv=2026-02-06&spr=https&st=2026-11-08T10%3A25%3A54Z&se=2026-11-08T11%3A25%3A54Z&sr=c&sp=r&sig=ZmXlv%2Fvy0lFgQh0bezaRg9fgOOIa4S6O6SCS4UkVtKU%3D)

## Document-Level Link Interception

A `click` event listener on `document` intercepts `<a>` tag clicks originating from inside the Shadow DOM. Links outside the Shadow DOM (in the host page) continue to work normally.

When an end-user clicks a link inside the embedded module:

1. The default navigation is prevented.
2. A `unqork-embed-navigate` CustomEvent is dispatched on `window` with the `href` in `event.detail`.

The listener also blocks navigations where the `href` attribute starts with `views/` or contains `undefined`—patterns that indicate Angular template paths or unresolved route expressions that would navigate the host page to an invalid URL if not intercepted.

## Shadow DOM and CSS Isolation

Shadow DOM creates a private boundary around the embedded module's DOM and CSS. Styles from the host page cannot reach inside, and styles from the module cannot leak out.

### Shadow DOM Structure

```
<unqork-app>                          ← Custom element (light DOM)
  #shadow-root (open)                 ← Shadow boundary
    <link rel="stylesheet" href="..."> ← Injected CSS
    <style>...</style>                 ← Scoped overrides
    <div id="centauri-root">           ← Angular bootstrap target
      <div ui-view>                    ← UI-Router viewport
        ...module content...
      </div>
    </div>
```

The outermost `&#x3C;unqork-app>` element is a placeholder in the host page's regular DOM. The shadow root attached to it creates a boundary: styles and DOM from the host page cannot reach inside, and styles from the module cannot affect the host page. Stylesheets are injected at the top of the shadow root so all styling scopes to the module. Below the stylesheets, the module's content tree mounts and renders module screens as end-users navigate.

### CSS Loading

Styles are loaded into the Shadow DOM from two sources:

| Source | Endpoint | Description |
| --- | --- | --- |
| Platform styles | `/fbu/uapi/styles` | Returns the environment's base CSS, including UnqorkAI platform styles. |
| Customer CSS | Environment-specific | Returns the customer-branded stylesheet for that environment. |

Both are fetched and injected as `&#x3C;link>` or `&#x3C;style>` elements inside the Shadow DOM. They do not affect the host page.

### Scoped Overrides

Certain styles are overridden for the embed context. For example, the workflow loader uses `position: absolute` instead of `position: fixed` to stay contained in the custom element boundary.

## Limitations

Some browser behaviors cannot be fully controlled by the navigation guard system. Review these limitations before building integrations that depend on browser history or fixed-position layouts.

| Limitation | Description |
| --- | --- |
| `position: fixed` | Elements styled `position: fixed` inside Shadow DOM are relative to the viewport, not the shadow host. Modals and loaders must use `position: absolute` to stay in the embedded module's boundary. |
| Font-face declarations | `@font-face` rules from the host page do not cross the Shadow DOM boundary. Fonts must be re-declared inside the shadow or loaded globally on the host page. |
| Global event listeners | `window.addEventListener` is shared across the shadow boundary. Events registered on `window` inside the embedded module are visible to the host page. |
| Browser back and forward buttons | Navigation guards block URL changes, so browser history is not updated. The back and forward buttons affect the host page history, not the embedded module. |
| Deep linking | The embedded module always starts fresh. Deep linking into a specific module state is not supported. |

---

**Changelog**

| Date | Change |
| --- | --- |
| 2026-06-15 | Renamed "Link Interception" to "Document-Level Link Interception"; added step-by-step explanation of link click behavior and CustomEvent dispatch. |
| 2026-06-10 | Expanded introduction paragraph to clarify the URL conflict between the embedded module and host page; added explanatory paragraph following the Shadow DOM Structure code block. |
| 2026-06-09 | Editorial pass: renamed heading "The Problem" to "Why Navigation Guards Are Needed"; added introductory descriptions to $browser Decorator, Shadow DOM and CSS Isolation, and Limitations sections; expanded table descriptions for non-experts. |
| 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.

A URL (uniform resource locator) is a unique identifier used to locate a resource on the internet. Also known as a web address.

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.

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.

Cascading Style Sheets (CSS) is a style sheet language used for presenting how a HTML or XML document looks to end-users.

AngularJS is a JavaScript framework added to an HTML page with a <script> tag. AngularJS extends HTML attributes and binds data to HTML using expressions.

GraphQL mutations let you create, update, and delete objects and fields in your data.

A definition

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.

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 Shadow Root is the root node of a Shadow DOM, which is a hidden DOM subtree attached to an element in the main DOM. It is a fundamental concept in Web Components, providing encapsulation for HTML, CSS, and JavaScript within a component.

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

Elements are are what you use to build Unqork applications. Elements include modules, workflows, Data Collections, Data Schema, and Record Collections.