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

> Resize host containers and respond to layout signals when the Web SDK switches to minimized ambient capture

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** UI 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>