> For the complete documentation index, see [llms.txt](https://developer.kizen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/floating-frames.md).

# Create Floating Frames

Include floating frames in your Kizen app to display interactive content that persists from page to page.

{% hint style="success" %}
**Audience:** Developers, solution architects

**Purpose:** Explains how to build floating frames as surfaces in Kizen apps
{% endhint %}

## Overview

*Floating frames* are expandable and collapsible overlays that appear above Kizen in the browser window (see Figure 1). They contain either custom HTML or embedded pages from elsewhere on the web. They load in their expanded state, although you can control this behavior through code, and they persist from page to page, so they are ideal for dialers, media players, and chat clients. They can also react to events as they happen. A frame that embeds a phone system, for example, can open a caller's contact record when the call starts and log the call as an activity when it ends.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2Fh48sLguQpeVepj2gKPMn%2Fappdev_floatingframes.png?alt=media&amp;token=0a1f3f18-cd2d-40b2-aa83-704902600003" alt="Two floating frames -- one called Clock, and one called Developer Docs -- appear as overlays on the Contacts page in Kizen." width="563"><figcaption><p><strong>Figure 1:</strong> Floating frames from an app.</p></figcaption></figure></div>

{% hint style="info" %}
**Note:** Kizen shows floating frames on all pages except for the login page, personal settings pages, embedded views, and builder pages, and generally hides them when modals are open, unless the frame was open before the modal. On all other pages, you can specify on which Kizen pages to show or hide a particular floating frame with the `match` and `ignore` configuration settings. For details, see [About `config.json` for floating frames](#about-config.json-for-floating-frames) below.
{% endhint %}

***

## Add a floating frame to your app

Add your floating frames to the `floatingFrames` directory in `src`. Place each floating frame in its own subdirectory with `config.json`, `script.js`, `styles.css` , and `message.js` files as needed, like this:

```
src/
└── floatingFrames/
    ├── adventure/
    │   ├── config.json
    │   ├── script.js
    │   └── styles.css
    └── dialer/
        ├── config.json
        ├── message.js
        ├── script.js
        └── styles.css
```

{% hint style="info" %}
**Note:** Depending on the floating frame, you might not need one or more of the files.
{% endhint %}

The following table describes these files:

| File          | Type                  | Purpose                                                                                                                             | Required? |
| ------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `config.json` | JSON                  | The configuration file for the floating frame.                                                                                      | Yes       |
| `script.js`   | JavaScript            | The script that runs when Kizen loads the floating frame.                                                                           | Yes       |
| `styles.css`  | Cascading Style Sheet | The styles for the content inside the floating frame. If the frame embeds content from an outside source, you don't need this file. | No        |
| `message.js`  | JavaScript            | A cross-document message handler. If the page in your frame doesn't send cross-document messages, you don't need this file.         | No        |

Floating frames also support event scripts. Place event scripts in the frame's `eventScripts` subdirectory. For more information on event scripts, see the [coding reference](https://kizen.github.io/app-engine/04-worker-runtime-api.html).

```
src/
└── floatingFrames/
    └── adventure/
        ├── config.json
        ├── script.js
        ├── styles.css
        └── eventScripts/
            ├── command.js
            └── restart.js
```

See below for details on each of these files.

### About `config.json` for floating frames

The configuration file for a floating frame sets the properties of the frame:

```json
{
  "name": "Clock Frame",
  "api_name": "clock_frame",
  "title": "Clock",
  "default_position": "bottom-right",
  "header_color": "#0000ff",
  "header_text_color": "#ffffff",
  "height": 120,
  "width": 240,
  "ignore": ["/details(/|$)"],
  "match": ["^/(dashboard|client|custom-objects)(/|$)"],
  "minimized_style": "circle",
  "minimized_config": {
    "icon": "calendar-days",
    "color": "#0000ff"
  },
  "when": "!{{userConfig.hideClock}}"
}
```

{% hint style="info" %}
**Note:** You might also find references to the `html` key for floating frames, but Kizen doesn't use its content. You can ignore this key.
{% endhint %}

The keys are as follows:

<table data-search="false"><thead><tr><th>Key</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><strong><code>name</code></strong></td><td>The internal name of the floating frame.</td><td>Yes</td></tr><tr><td><strong><code>api_name</code></strong></td><td>The API name of the floating frame in all lowercase letters. If you don't specify a value for this key, the system automatically generates one based on the name of the floating frame's subdirectory.</td><td>No</td></tr><tr><td><strong><code>title</code></strong></td><td>The title of the floating frame. The title appears in the frame's title bar.</td><td>Yes</td></tr><tr><td><strong><code>default_position</code></strong></td><td><p>The default position of the floating frame:</p><ul><li><code>bottom-left</code>. The floating frame appears in the bottom left corner of the browser window to start.</li><li><code>bottom-left-fixed</code>. The floating frame is pinned to the bottom left corner of the browser window.</li><li><code>bottom-right</code>. The floating frame appears in the bottom right corner of the browser window to start.</li><li><code>bottom-right-fixed</code>. The floating frame is pinned to the bottom right corner of the browser window.</li></ul></td><td>No</td></tr><tr><td><strong><code>header_color</code></strong></td><td>The background color of the title bar. Set the value to a hexadecimal color code, CSS color, or color keyword.</td><td>No</td></tr><tr><td><strong><code>header_text_color</code></strong></td><td>The color of the text in the title bar. Set the value to a hexadecimal color code, CSS color, or color keyword.</td><td>No</td></tr><tr><td><strong><code>height</code></strong></td><td>The height of the floating frame in pixels.</td><td>No</td></tr><tr><td><strong><code>width</code></strong></td><td>The width of the floating frame in pixels.</td><td>No</td></tr><tr><td><strong><code>ignore</code></strong></td><td>A list of regular expressions that describe on which page paths to hide the floating frame. Kizen always hides floating frames on the login page, personal settings pages, embedded views, and builder pages.</td><td>No</td></tr><tr><td><strong><code>match</code></strong></td><td>A list of regular expressions that describe on which page paths to show the floating frame. Kizen never shows floating frames on the login page, personal settings pages, embedded views, and builder pages.</td><td>No</td></tr><tr><td><strong><code>minimized_style</code></strong></td><td><p>The appearance of the collapsed floating frame:</p><ul><li><code>circle</code>. The floating frame appears as an icon in a circle in the bottom left or right corner of the browser window, depending on the position of the frame. The user selects the circle to expand and collapse the frame. You must use this style with a fixed-position floating frame.</li><li><code>bar</code>. The floating frame appears as its title bar only. The user selects the bar to expand and collapse the frame.</li><li><code>none</code>. The floating frame disappears from the screen. The user can't interact with it directly, but it remains expandable and collapsible through code.</li></ul></td><td>No</td></tr><tr><td><strong><code>minimized_config</code></strong></td><td>An object that describes the collapsed floating frame when the minimized style is <code>circle</code>. These keys have no effect when the minimized style is <code>bar</code> or <code>none</code>.</td><td>No</td></tr><tr><td><strong><code>minimized_config.icon</code></strong></td><td>The name of the icon that appears in the floating frame's circle. For the available icons, see the <a href="https://kizen.github.io/app-engine/index.html">coding reference</a>.</td><td>No</td></tr><tr><td><strong><code>minimized_config.color</code></strong></td><td>The color of the floating frame's circle. Set the value to a hexadecimal color code, CSS color, or color keyword.</td><td>No</td></tr><tr><td><strong><code>when</code></strong></td><td>A condition that determines when to show the floating frame on the screen. For more information, see the <a href="https://kizen.github.io/app-engine/index.html">coding reference</a>.</td><td>No</td></tr></tbody></table>

{% hint style="info" %}
**Note:** Floating frames don't have a key to control their starting state, but you can write logic to achieve the same effect. To collapse a frame on load, call `this.collapse()` from its script. To expand a collapsed frame, call `this.expand()`.
{% endhint %}

### About `script.js` for floating frames

The JavaScript file for a floating frame is the main script for the frame. Kizen runs the script when the frame loads. The script sets the starting state of the frame.

The script can use standard JavaScript, most web APIs available to Web Workers, and Kizen's runtime API, including methods for controlling the frame. Because the script acts as the signed-in user, it can do whatever the user can do in Kizen, with the same permissions, and it knows their name and currently active business. However:

* **A floating frame script doesn't keep track of which record the user is viewing.** However, it can get the user's URL and determine the current record from that, and it can receive a notification when the user's URL changes to react to record pages.
* **A floating frame script controls only its own frame.** It can show toasts and modals and navigate to other pages in Kizen, but it can't otherwise change the browser window outside the frame.
* **A floating frame script runs only while Kizen is open.** Closing Kizen stops the script. For tasks that need to run on their own, use an agentic workflow code step instead.
* **A floating frame script starts fresh on each run.** To carry values from previous runs, store them in the user's configuration or as short-term session data. For details, see the [coding reference](https://kizen.github.io/app-engine/glossary.html#session-data).
* **A floating frame script must finish before the user can interact with the frame.** Code that runs on a loop or long delay, like a clock that updates its output every minute, belongs in an event script.

To paint content into the frame, use one of two methods. Use `this.outputUI()` for custom HTML and CSS:

```javascript
this.outputUI(`
  <form class="adventure" data-script="command">
    <p class="adventure__room">Maze</p>
    <p class="adventure__text">
      You are in a maze of twisty little passages, all alike.
    </p>
    <label class="adventure__prompt" for="player-command">&gt;</label>
    <input id="player-command" name="player-command" type="text" autocomplete="off" required>
    <button type="submit" class="adventure__button">Go</button>
    <button type="button" class="adventure__button" data-script="restart">Restart</button>
  </form>
`);
```

{% hint style="info" %}
**Note:** The **`data-script`** attributes in this example indicate the event scripts to run when the user interacts with the HTML elements in the floating frame. For more information on **`data-script`**, see the [coding reference](https://kizen.github.io/app-engine/glossary.html#data-script).&#x20;
{% endhint %}

The method takes a single HTML string as its argument. The CSS comes from the frame's `styles.css` file or from inline **`style`** attributes in the HTML. For security, Kizen strips out `<script>` tags, event handlers, and `javascript:` links but leaves SVG, images, and `<iframe>` elements. For more information, see the [coding reference](https://kizen.github.io/app-engine/11-output-ui-iframes-frames.html#thisoutputuimarkup-options).

To embed a live web page, use `this.outputIframe()`:

```javascript
this.outputIframe('https://developer.kizen.com');
```

{% hint style="info" %}
**Note:** Another way to embed a page in a floating frame is to write an `<iframe>` element into your custom HTML with `this.outputUI()`.
{% endhint %}

The page loads from its own server and runs its own code, so it can update itself. The address must start with `https://`, and the site must allow embedding. For more information, see the [coding reference](https://kizen.github.io/app-engine/11-output-ui-iframes-frames.html#thisoutputiframeurl-allow-sandbox-options).

{% hint style="info" %}
**Note:** Kizen loads embedded web pages through a frame proxy at `https://plugin-assets.kizen.com`. If you need to update your site to make it embeddable in Kizen, allow the proxy's domain, not just Kizen's. For more information on the frame proxy, see the [coding reference](https://kizen.github.io/app-engine/11-output-ui-iframes-frames.html#the-frame-proxy).
{% endhint %}

### About `styles.css` for floating frames

The style sheet for a floating frame provides the style definitions for the classes in the frame's custom HTML:

```css
.adventure {
  display: grid;
  grid-template-columns: auto 1fr auto;
  align-content: start;
  gap: 8px;
  height: 100%;
  margin: 0;
  padding: 12px;
  box-sizing: border-box;
  background-color: #000000;
  color: #33ff33;
  font-family: ui-monospace, Menlo, Consolas, monospace;
  font-size: 14px;
  line-height: 1.4;
}

.adventure__room,
.adventure__text {
  grid-column: 1 / -1;
  margin: 0;
}

.adventure__room {
  font-weight: 700;
}

.adventure__prompt {
  align-self: center;
}
```

You don't need a style sheet if your frame uses `this.outputIframe()` to embed a live web page.

{% hint style="info" %}
**Note:** Custom HTML content can inherit styling from Kizen before your style sheet applies. Therefore, for best results, explicitly set style properties for your classes instead of relying on default settings.
{% endhint %}

### About `message.js` for floating frames

The `message.js` file for a floating frame is a script that runs when Kizen's browser window receives a cross-document message on a page with the frame. Cross-document messages usually come from the page embedded in the frame, but not necessarily. Any message that Kizen receives, except for Kizen's own messages to itself and messages about Kizen payments, triggers the frame's `message.js` script.

The message itself is in **`this.args.eventData`**. Check that the message you receive is the one you expect, and direct its handling logic to an event script with `this.communicate.runFrameScript()`, like this:

```js
const message = this.args.eventData;

// Ignore anything that isn't from the Acme dialer page.
if (message?.source !== 'acme-dialer') return;

switch (message.type) {
  case 'call-started':
    // Find and open the caller's contact record.
    this.communicate.runFrameScript('dialer_frame', 'showCaller', {
      phone: message.phone,
    });
    break;

  case 'call-ended':
    // Log the call as an activity on the contact.
    this.communicate.runFrameScript('dialer_frame', 'logCall', {
      phone: message.phone,
      durationSeconds: message.duration,
    });
    break;

  case 'call-missed':
    // Remind the user to call back.
    this.communicate.runFrameScript('dialer_frame', 'logMissedCall', {
      phone: message.phone,
    });
    break;
}
```

{% hint style="info" %}
**Note:** For more information on the **`this.args`** object, see the [coding reference](https://kizen.github.io/app-engine/04-worker-runtime-api.html#thisargs).
{% endhint %}

To reply to the embedded page, use `this.communicate.sendMessageToOwnFrame()`.

{% hint style="info" %}
**Note:** If the embedded page in the floating frame navigates to another site, messaging stops until the frame repaints.
{% endhint %}

***

## What's next?

Continue to [Create Pages](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/embedded-pages.md) to learn how to include pages in your app.

<details>

<summary>Related Topics</summary>

* [Apps](https://developer.kizen.com/docs/apps-and-integrations/plugin-development.md)
* [Work with Marketplace Apps](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/work-with-marketplace-apps.md)
* [Work with Business Apps](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/work-with-business-apps.md)
* [Develop Apps](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps.md)
* [Work with KiCode](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/work-with-kicode.md)
* [Create App Surfaces](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces.md)
* [Create Toolbar Items](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/toolbar-items.md)
* [Create Pages](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/embedded-pages.md)
* [Create Blocks](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/embedded-blocks.md)
* [Create Data Adornments](https://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/data-adornments.md)

</details>

***


---

# 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://developer.kizen.com/docs/apps-and-integrations/plugin-development/develop-apps/create-app-surfaces/floating-frames.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.
