--- title: "Browser Preview" slug: "browser-preview" tags: ["previewing-applications"] status: "update" updated: 2026-10-15T14:26:14Z published: 2026-10-15T14:25:39Z canonical: "docs.unqork.io/browser-preview" --- > ## 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. # Browser Preview Browser Preview runs a workspace application in its own tab inside the Unqork platform, using the application's assigned style and runtime. Creators use Browser Preview to test an application as an Express role or a real end-user. They can also try URL query parameters and mark up the rendered page for the UnqorkAI agent. For testing in a full browser tab with the preview bar, use [Express View](/unqorkai/docs/viewing-previewing-applications). ## Opening Browser Preview The Browser Preview control is the ![Globe](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261015_142536_48871556dc3749be976df6359c4c72d2.svg?sv=2026-02-06&spr=https&st=2026-11-04T08%3A55%3A31Z&se=2026-11-04T09%3A55%3A31Z&sr=c&sp=r&sig=35QJaI2s8u%2FK8SolxFWdrKphhitR6Hdo%2FXpPsjMfpiE%3D) (**globe**) at the far left of the tab bar. The control displays only when the workspace contains at least one application with an entry-point module. ![The tab bar with the Browser Preview globe control at the far left, before the workspace and module tabs.](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261015_142536_9aaa44b7250b4356ae542760a51891a6.webp?sv=2026-02-06&spr=https&st=2026-11-04T08%3A55%3A31Z&se=2026-11-04T09%3A55%3A31Z&sr=c&sp=r&sig=35QJaI2s8u%2FK8SolxFWdrKphhitR6Hdo%2FXpPsjMfpiE%3D) To open Browser Preview, complete the following: 1. At the far left of the tab bar, select ![Globe](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261015_142536_48871556dc3749be976df6359c4c72d2.svg?sv=2026-02-06&spr=https&st=2026-11-04T08%3A55%3A31Z&se=2026-11-04T09%3A55%3A31Z&sr=c&sp=r&sig=35QJaI2s8u%2FK8SolxFWdrKphhitR6Hdo%2FXpPsjMfpiE%3D) (**Browser Preview**). 2. From the menu, select an application. Browser Preview opens at the application's entry-point module. While a preview is running, the globe control displays the application name and splits into two parts: | Part | Description | | --- | --- | | **Application name** | Returns to Browser Preview from any other tab. | | **Browser Preview Options** | Opens the application menu. Select another application to preview it from its entry-point module, or select **Close Browser Preview** to end the preview. | ### What Browser Preview Renders In a versioned application, Browser Preview renders the branch, version, or commit currently selected in the [checkout pill](/unqorkai/docs/manage-versions). Switching branches or versions in a Module Builder tab reloads the preview on the new selection. A module opened from a published version or a historic commit is read-only. To make changes, switch to a branch. For details, see [Versioning Troubleshooting](/unqorkai/docs/troubleshooting-versioned-applications). Opening a historic commit from Branch History renders that commit until the selection returns to a branch or version. For more about branches and versions, see [Application Versioning](/unqorkai/docs/application-versioning-overview). If the entry-point module has no components, or redirects when it loads, Browser Preview opens another module from the application instead. When no module in the application has components, the canvas displays **Nothing to preview just yet**. When a Creator selects an empty module from the module menu, the canvas displays the module name followed by **is empty**. ## Browser Preview Toolbar The toolbar displays at the top of the preview. The following table lists its controls from left to right. | Control | Description | | --- | --- | | **Back** and **Forward** | Move through the pages visited in the preview. The preview keeps its own history, separate from the browser history. Available in builder mode only. | | **Reload Preview** | Reloads the application in the preview. | | **URL bar** | Displays the route of the module currently in the preview, for example `#/display/{moduleId}`. The route is read-only. Select **Add Query Param** to append query parameters. | | **Module name** | Displays the name of the module currently in the preview. Select the name to open the module in the Module Builder. When the application has more than one module, select **Go to Another Module** to choose a different one. The entry-point module is labeled **Entry**. | | **Mark Up Preview** | Turns markup mode on or off. Available in builder mode only. | | **Viewport Size** | Sets the preview width to **Mobile (375px)**, **Tablet (768px)**, **Laptop (1024px)**, or **Desktop (1440px)**. The default is **Desktop (1440px)**. When the canvas is narrower than the selected width, the preview scales down to fit and keeps the selected layout. | | **Zoom** | Sets the zoom level from **50%** to **200%**. At **100%**, the preview fits the canvas. Select **Reset View** to return to **100%**. | | **Preview as Role** | Renders the application as a selected Express role. Available in builder mode only. | | **Session controls** | Display who is logged in to the preview, and switch between builder mode and live mode. | ## Builder Mode and Live Mode Browser Preview runs in one of two modes. Creators switch between modes using the session button at the right of the toolbar. | Mode | Description | Best For | | --- | --- | --- | | **Builder mode** | Runs the application with the Creator's own platform session. Builder mode is the default. | Checking layout, testing Express roles and query parameters, and marking up the preview. | | **Live mode** | Runs the application at the environment's Express URL, with a real end-user login. | Testing login, SSO, and logout, and checking what a specific end-user account can see and do. | In live mode, **Preview as Role** is hidden and the URL bar is read-only. **Back**, **Forward**, and **Mark Up Preview** are unavailable. > [!WARNING] > Data entered in Browser Preview, in builder mode or live mode, is saved as real submission data in the environment. Use test accounts or clearly labeled test data to avoid affecting reports, workflows, or other downstream processes. ### Session Controls The session controls at the right of the toolbar display a login status and one button. In builder mode, the status displays **Logged in as** followed by the Creator's name. In live mode, the status displays the end-user's name, or **Not logged in** when the preview has no logged-in end-user. The button changes with the preview state: | Preview State | Button | Result | | --- | --- | --- | | Builder mode | **Log In as Another User** | Switches to live mode and displays the application's login screen. | | Live mode, end-user logged in | **Log Out** | Logs the end-user out and displays the application's login screen. | | Live mode, no end-user logged in | **Return to Your IDE Session** | Switches back to builder mode with the Creator's own session. | The canvas displays **Loading preview...** during each switch. ### Logging In as an End-User To test the application as a specific end-user, complete the following: 1. In the toolbar, select **Log In as Another User**. Browser Preview logs out any earlier end-user session and displays the application's login screen. 2. Log in with the end-user's credentials. Browser Preview returns to the module that was in the preview, and the session controls display the end-user's name. To return to builder mode, complete the following: 1. In the toolbar, select **Log Out**. 2. Select **Return to Your IDE Session**. If the application has a custom logout module, **Log Out** displays that module instead of the login screen. The end-user's name can take a few seconds to update in the session controls after a login or logout. To create or manage end-user accounts, see [Express User Administration](/unqorkai/docs/express-user-administration). ### Signing In with SSO When an application uses SSO (Single Sign-On), the identity provider's sign-in page can't load inside the preview. Live mode displays a **Sign in to continue** card instead. To sign in with SSO, complete the following: 1. On the card, select **Sign In in a New Tab**. The identity provider's sign-in page opens in a new browser tab. 2. Complete sign-in in the new tab. Browser Preview detects the new session, closes the sign-in tab when the browser permits it, and reloads the application. If sign-in doesn't finish in about two minutes, the card prompts the Creator to close the other tab and try again. ### Enabling Live Mode for an Environment > [!WARNING] > Live mode requires the environment's **Frame Ancestors List** to include the Unqork platform address. Builder mode works without this setting. When the address is missing, live mode displays **Live preview isn’t enabled for this environment** with the exact address to add. An environment administrator adds the address in Environment Administration, in the **Frame Ancestors List** setting. For details, see [Express Content Security Policy (CSP)](/unqorkai/docs/environment-administration#express-content-security-policy-csp). After the change is saved, select **Reload Preview** to check again. ## Testing Roles and Query Parameters In builder mode, Creators can change how the application loads without editing it. Browser Preview always uses the application's assigned style and runtime. ### Previewing as an Express Role To preview the application as an Express role, complete the following: 1. In the toolbar, select **Preview as Role**. 2. Select an Express role. Browser Preview reloads the application with that role's permissions applied, and the control's tooltip displays the selected role name. Until a Creator selects a role, Browser Preview uses the Creator's own access. In [Production environments](/unqorkai/docs/environment-levels), only Creators with the Administrator Creator Role can preview as an Express role. Creators whose Express role still has the deprecated [Designer Access (Super-user)](/unqorkai/docs/environment-administration) option can also do so. For other Creators, the application loads with their own access. To create and manage roles, see [Express Role Administration](/unqorkai/docs/express-role-administration). ### Adding Query Parameters To add query parameters to the preview, complete the following: 1. In the URL bar, select **Add Query Param**. 2. Enter the query string, for example `status=open`. 3. Press **Enter**. Browser Preview reloads the module with the parameters added to its route. To remove the parameters, select **Remove query param** in the field, or press **Escape**. Query parameters always apply to the module the preview opened at, even after navigating to another page in the application. In live mode, the URL bar is read-only and query parameters don't apply. ## Marking Up the Preview Creators can draw on the rendered application and send the result to the UnqorkAI agent as an image. To mark up the preview, complete the following: 1. In the toolbar, select **Mark Up Preview**. The application pauses, and the markup controls display at the top center of the preview. 2. Draw on the preview using **Draw** or **Box Select**. 3. Select **Send to Agent**. Browser Preview captures the visible preview with the markup, attaches the image to the agent chat message, and closes markup mode. 4. In the agent chat, describe the change, then send the message. To exit markup mode without sending, select **Mark Up Preview** again. The markup controls include the following: | Control | Description | | --- | --- | | **Box Select** | Draws a rectangle around an element or region. | | **Change Color** | Opens a color picker for a custom markup color. | | **Color swatches** | Sets the markup color to **Red**, **Green**, **Black**, or **White**. The default is **Red**. | | **Draw** | Draws freehand lines. Draw is the default tool. | | **Send to Agent** | Attaches the marked-up preview to the agent chat. Available after at least one mark is drawn. | | **Undo** | Removes the last mark. | > [!WARNING] > **Mark Up Preview** is available in builder mode only, and requires the AI features of UnqorkAI to be turned on for the organization. If the capture fails, the markup stays in place so the Creator can try **Send to Agent** again. ## Agent Context from Browser Preview While Browser Preview is the active tab, the agent chat receives the previewed application and the module currently in the preview as context. The context badge in the agent chat displays the application name after the **Previewing** label. When the preview moves off the entry-point module, the badge adds the module name. The badge updates when the Creator navigates in the preview or selects another module from **Go to Another Module**. The badge clears when the Creator switches to another tab or selects **Close Browser Preview**. For more about working with the agent, see [UnqorkAI Build Agent](/unqorkai/docs/build-agent-overview). ## Links That Leave the Application Browser Preview keeps most navigation inside the preview. The following table describes how links that leave the current page behave. | Link Type | Behavior in Browser Preview | | --- | --- | | Link in the application that opens a new tab for end-users. | Opens in the preview. A notice explains that end-users get a new browser tab. | | Link to a site outside the application. | Doesn't load in the preview. A notice displays the destination and an **Open in new tab** button. | --- **Changelog** | Date | Change | | --- | --- | | 2026-10-14 | Moved to Previewing Applications and rewritten to cover the full Browser Preview feature, including live mode, role and query parameter testing, and agent context. | | 2026-09-24 | Browser Preview renders the selected branch, version, or commit in versioned applications. | | 2026-08-19 | Initial publication. Documents Browser Preview annotation tools, Send to Agent, and Application Versioning tab bar controls. | Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. The Unqork front-end application framework that delivers Creator-built applications to end-users. Express is the layer end-users interact with—the published forms, screens, and navigation built in the Module Builder. Express is distinct from Express View, which is a Creator-facing preview tool in the IDE. 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 URL (uniform resource locator) is a unique identifier used to locate a resource on the internet. Also known as a web address. A query lets you retrieve, access, manipulate, and delete data in a database. In Unqork an application is a program used to perform specific tasks. An application can be one of two types: workflow or module. Rendering is the process of loading components and displaying the final result on the front-end screen. Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. Single Sign-On is an authentication scheme that enables users to use one set of login credentials across multiple services. 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. Identity provider (IdP) provide a service that creates, manages, and verifies users' digital identities, allowing them to securely authenticate and access different applications or services. A string is an object that represents a sequence of characters. Strings typically hold data represented in text form. 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.