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

# Minimized Layout Implementation

> Learn about the host responsibilities, layout signals, and validation for minimized ambient layout in the headed Web SDK

When the Suki Web SDK minimizes during ambient capture, the UI transforms into a compact floating widget. Recording and session behavior stay the same; the change is so your application can reclaim screen space for the chart or other primary content.

The SDK remains attached to your original **root element**. In minimized layout the iframe uses **fixed** positioning, so you must **shrink or move your host container** around that mount. If you leave the old reservation in place, you will see a large empty region where the full headed panel used to sit.

This guide outlines **host code** responsibilities versus what the **Web SDK** already handles. For mount placement, overflow, and transform guidance, read the [Minimized layout overview](/web-sdk/minimized-layout/overview).

<Note>
  Minimized layout applies only to the **headed Web SDK**. It requires **Web SDK `3.1.0`** or later.
</Note>

## Layout values from the hosted iframe

The hosted iframe sends one layout value at a time. Treat `minimized` and `minimized-paused` the same in your host layout: both mean the small overlay is active, so you should free the area you reserved for the full headed panel. When the value is `expanded`, give that slot back to the full panel.

| Status                 | Description                                                              | Action                                                                       |
| ---------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| **`expanded`**         | The full headed panel is active in your mount slot.                      | Restore your usual width, height, min sizes, and flex rules for that region. |
| **`minimized`**        | The SDK is a small floating widget; ambient capture can still be active. | Collapse or hide your mount wrapper so chart content can expand.             |
| **`minimized-paused`** | The SDK uses minimized chrome while ambient is paused.                   | Collapse the host slot the same way you do for **`minimized`**.              |

## How to implement minimized layout

<Steps>
  <Step title="Initialize and mount">
    Use a **root element** reserved for the iframe, the same as the **`rootElement`** you pass to **`mount`** in **`@suki-sdk/js`**, or the parent tree where you render **`SukiAssistant`** in **`@suki-sdk/react`**.
  </Step>

  <Step title="Collapse your mount wrapper">
    When **`layout`** is not **`expanded`**, set **`width`**, **`minWidth`**, **`height`**, and **`minHeight`** to **`0`**, or **hide the column** with flex rules (including **`flex-basis`** when that is what reserves space).
  </Step>

  <Step title="Maintain visibility on the mount">
    Keep **`overflow: visible`** on the **mount node** while minimized so the **fixed-position** iframe is not clipped by a scrolling or clipping ancestor.
  </Step>

  <Step title="Restore dimensions when expanded">
    When **`layout`** returns to **`expanded`**, restore your normal CSS dimensions or **flex basis** for the headed panel.
  </Step>

  <Step title="Reclaim space for core content">
    The iframe **remains a child of your mount node** even when minimized. Because it is **fixed-positioned**, the parent does not need to stay large; your application should **reclaim that space** for core content next to or behind the widget.
  </Step>
</Steps>

<Note>
  **In React**

  * The **`SukiAssistant`** component **does not** automatically collapse its container when the SDK minimizes.
  * You must use the **`onLayoutChange`** prop to collapse, hide, or restyle the container in your layout.
</Note>

### Code examples

Subscribe to **`ui:layout-change`** on the **`@suki-sdk/js`** instance after **`initialize`**.

In **`@suki-sdk/react`**, drive a **wrapper** around **`SukiAssistant`** from **`onLayoutChange`** so your slot tracks the SDK (the React sample shows a typical wrapper with inline styles; use classes or tokens in production if you prefer).

<View title="JavaScript" icon="js">
  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  sdk.on("ui:layout-change", ({ layout }) => {
    // layout: "expanded" | "minimized" | "minimized-paused"
    const mount = document.getElementById("suki-root");

    if (layout === "expanded") {
      mount.style.width = "";
      mount.style.minWidth = "";
      mount.style.height = "";
      mount.style.minHeight = "";
    } else {
      mount.style.width = "0";
      mount.style.minWidth = "0";
      mount.style.height = "0";
      mount.style.minHeight = "0";
    }

    mount.style.overflow = "visible";
  });
  ```
</View>

<View title="React" icon="react">
  ```tsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { useState } from "react";
  import { SukiAssistant } from "@suki-sdk/react";

  // Minimal API: SukiAssistant must receive onLayoutChange; you collapse a parent you own.
  // layout: "expanded" | "minimized" | "minimized-paused"
  // onLayoutChange={(layout) => setIsMinimized(layout !== "expanded")}

  export function HostWithSuki({ encounter }) {
    const [isMinimized, setIsMinimized] = useState(false);

    return (
      <div
        className="suki-mount-host"
        data-minimized={isMinimized}
        style={
          isMinimized
            ? {
                width: 0,
                minWidth: 0,
                height: 0,
                minHeight: 0,
                overflow: "visible",
              }
            : {
                overflow: "visible",
                // Restore width, height, and flex values your layout uses when expanded.
              }
        }
      >
        <SukiAssistant
          encounter={encounter}
          onLayoutChange={(layout) => {
            // layout: "expanded" | "minimized" | "minimized-paused"
            setIsMinimized(layout !== "expanded");
          }}
        />
      </div>
    );
  }
  ```
</View>

<Warning>
  Without **`onLayoutChange`** (and without applying the same rules on a wrapper you control), a **360×640** (or similar) **invisible block** can remain in your layout even when the SDK is minimized, which displaces chart columns and other host content.
</Warning>

<Tip>
  Prefer class names, design tokens, or layout components instead of inline styles in production; the samples above show the state transition clearly.
</Tip>

## What you do not need to do

* **Iframe sizing:** do not re-implement iframe **width**, **height**, or **positioning**. The **`@suki-sdk/js`** package controls iframe geometry for **expanded** and **minimized** states when minimize is allowed. You only adjust **your** mount container.
* **Space recovery:** if your layout **does not** have an empty slot to reclaim (for example the SDK sits in a **dedicated overlay** and nothing else needs to grow into a reserved column), you can **skip** handling **`ui:layout-change`** for layout recovery. You should still follow [Configure the mount point](/web-sdk/minimized-layout/overview#configure-the-mount-point) on the overview so **fixed** positioning and stacking behave predictably.

## Validate in a test environment

Follow these steps to verify your integration end to end.

<Steps>
  <Step title="Enable the feature">
    To enable the feature for your organization, contact support.
  </Step>

  <Step title="Start a session">
    Initiate **ambient** capture from the headed SDK UI or your controlled entry point. When capability and session state allow it, the iframe should become a **small floating widget**.
  </Step>

  <Step title="Confirm the layout shift">
    * **In JavaScript:** after **`ui:layout-change`** fires and you **collapse the mount**, your main content should grow into the reclaimed space.

    * **In React:** use **`onLayoutChange`** to collapse your container whenever **`layout`** is not **`expanded`**, and confirm the shift matches what you expect.
  </Step>

  <Step title="Verify ambient dialogs">
    Confirm that **ambient** dialogs (for example **cancel**, **insufficient context**, and **audio-below-threshold**) appear correctly on the **minimized** surface when the product allows them there.
  </Step>
</Steps>

<Note>
  If you are unsure how minimize is enabled for staging or production, ask your Suki integration contact for the current rollout process.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget is misplaced or clipped">
    This is usually caused by **`transform`**, **`filter`**, or **`will-change`** on an **ancestor** of the mount. **Relocate** the mount outside transformed or filtered containers, set **`overflow: visible`** on the mount while minimized, and retest.

    Read [Avoid transformed ancestors](/web-sdk/minimized-layout/overview#avoid-transformed-ancestors) to learn more about how to avoid this issue.
  </Accordion>

  <Accordion title="Chart does not expand when the SDK minimizes">
    Explicitly set **`width`**, **`height`**, **`minWidth`**, **`minHeight`**, or **`flex-basis`** to **zero** (or hide the column) when **`layout`** is not **`expanded`**. Without collapsing, the layout keeps reserving the prior panel size (for example **360×640**). In React, drive that collapse from **`onLayoutChange`**.
  </Accordion>

  <Accordion title="Ambient dialogs are hard to see">
    Verify the **feature flag** or **Remote Config** rollout enables minimize for the **user or organization**, and confirm the iframe is not clipped. Check **`z-index`** stacking and **`overflow`** on ancestors.
  </Accordion>
</AccordionGroup>