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

> Learn when the Headed Web SDK minimizes during Ambient or Re-ambient sessions and how to prepare your host layout

<div className="quick-summary-wrapper">
  <div className="quick-summary-header">
    <span className="quick-summary-icon" aria-hidden="true" />

    <span className="quick-summary-title">Quick summary</span>
  </div>

  <div className="quick-summary-content">
    Minimized layout changes the Headed Web SDK into a compact, viewport-aligned widget during supported ambient sessions. Your host application, keeps the chart visible while the Web SDK preserves recording controls. This feature is available in version `3.1.0` and later.
  </div>

  <div className="quick-summary-footer">
    <span className="quick-summary-footer-icon" aria-hidden="true" />

    <span className="quick-summary-footer-text">Last updated:</span>
    <span className="quick-summary-footer-date">August 2026</span>
  </div>
</div>

**Minimized layout** enables an alternate headed UI mode for **ambient** sessions in the Headed Web SDK. The hosted Suki iframe shrinks to a small overlay so your application stays the main focus. Recording, pause, cancel, and generate still run through the same session;
only the surface area of the iframe changes to a small overlay.

<Note>
  **Important:**

  * This applies only to the <strong>Headed Web SDK</strong>, where Suki runs inside the SDK iframe. It does <strong>not</strong> apply to the <strong>Headless Web SDK</strong>, headless-only apps, or API-only integrations.
  * Minimized layout frees up screen space for the EHR/chart while maintaining ambient awareness.
  * On critical errors, Web SDK automatically re-expands the UI to ensure visibility of required actions.
  * You control the surrounding layout to reclaim space for your own UI. You **do not control** when minimized layout is enabled.
</Note>

## When minimized layout is available

In the headed iframe, auto-minimize runs when the following conditions are met:

* **Ambient and Re-ambient:** The minimized UI tracks an active ambient-style session in that iframe. It is not a partner-controlled "small UI" mode for non-ambient flows.
* **Minimize capability:** The hosted iframe evaluates policy and runtime constraints for the current user or organization before shrinking. The UI requests minimized layout only when **minimize capability** is on. If it is off, the Headed Web SDK stays **expanded** and auto-minimize does not run.

## Common integration patterns and use cases

Plan minimized layout around the host UI that must remain usable while ambient or re-ambient capture continues.

<CardGroup cols={2}>
  <Card title="Chart-First Workspace" icon="table-columns">
    Keep the patient chart or order workflow visible while the minimized widget provides pause, cancel, and note-generation controls.
  </Card>

  <Card title="Constrained Web Layout" icon="window">
    Use a collapsible grid, flex, or split-view slot so short, narrow, or portrait layouts can reclaim the space reserved for the expanded SDK.
  </Card>

  <Card title="Stable Overlay Mount" icon="layer-group">
    Mount the SDK on a stable ancestor without transformed or clipping wrappers so the fixed widget stays aligned and visible.
  </Card>

  <Card title="Visible Error Recovery" icon="triangle-exclamation">
    Keep the expanded SDK area available because critical errors can return the interface to the full headed view for recovery actions.
  </Card>
</CardGroup>

<Note>
  When minimize capability is off, the iframe stays **fully expanded** for ambient sessions and partners will not see auto-minimize.
</Note>

## Minimized layout capabilities

<CardGroup cols={2}>
  <Card title="Auto-Minimize" icon="window">
    When **ambient** (or **re-ambient**) **recording** is active and minimize is supported, the UI moves to a small rectangular overlay automatically. No separate partner action is required to shrink the iframe.
  </Card>

  <Card title="Core Controls on the Widget" icon="sliders">
    From the minimized UI users can **pause** (center), **cancel** (top-left), or **generate notes** (bottom-right) without opening the full headed panel. Cancel still uses the standard confirmation step before ending the session.
  </Card>
</CardGroup>

<Card title="Auto-Expand on Errors" icon="triangle-exclamation">
  On **409 Conflict** (for example session collisions or state locks), the SDK exits minimized layout and returns to the full headed view so the user can complete **Remote Completion** or other recovery UI.
</Card>

## How Minimized layout works

Suki turns on **minimize capability** in the hosted configuration for **eligible** partners and users. On your side, ship a **correct mount** and **reclaim layout space** so the minimized iframe does not leave a large empty slot in your app.

<Note>
  Contant Suki Support to enable minimize capability for your organization.
</Note>

### Configure the mount point

In Minimized layout, the SDK draws a small overlay using `position: fixed`. Fixed positioning is resolved against the **nearest containing block**, not always the browser viewport. If that block is wrong, the widget can shift, clip, or disappear.

Follow these rules when you choose the DOM node where the Web SDK mounts.

#### Where to mount

Mount the Headed Web SDK root on a stable, full-viewport ancestor, for example:

* Mount on `document.body`.
* A full-height app shell you control (main layout wrapper).
* A side panel that is **not** nested under an element that applies CSS transforms.

Prefer a host layout with a **dedicated slot** (for example a flex or grid track) sized for the full headed iframe while expanded, and **collapsible** when minimized so the rest of your UI can grow into the freed space.

<Note>
  Do not mount inside **modals**, **animated drawers**, or other subtrees that sit under transformed or heavily layered stacking ancestors. Those patterns can trap or clip `position: fixed` descendants, misalign the widget to the viewport, or break expected z-order.
</Note>

#### Avoid transformed ancestors

Do not mount the SDK inside subtrees that set `transform`, `filter`, or `will-change` in a way that creates a new containing block for fixed descendants. Those properties create new stacking contexts; `position: fixed` on the iframe may then resolve to the wrong box, which can look like offscreen placement, clipping, or odd layering.

If you cannot move the mount, remove or isolate those properties on ancestors above the mount node.

#### Keep overflow visible

While minimized, set the mount element (and any immediate wrappers you own) to `overflow: visible` so the fixed iframe is not clipped by `overflow: hidden` or `auto` scrollers.

<Tip>
  If your layout normally clips overflow, toggle visibility only around the minimized state, or mount on a sibling outside the scrolling region.
</Tip>

### Reclaim screen space

The SDK sizes and positions the **iframe** for both headed and minimized modes. Your app still owns the **mount container** around that iframe. If that container keeps the same width and height as the full headed panel (often about **360×640** px reserved in your layout), you will see a large empty gap even though the SDK UI is already small.

After minimize, shrink or collapse that container so your grid, flex, or split view can grow into the freed space.

**Recommended approaches**:

* Drop or lower `min-height` / `min-width` on the mount wrapper while minimized.
* Switch the mount slot to `auto` height, a smaller fixed height, or hide a dedicated “SDK column” until the user expands again.

Match the reserved area to the minimized footprint you want, or remove the reservation entirely if the widget is fully `fixed` and does not need layout flow space.

## Next steps

<Icon icon="file-lines" iconType="solid" /> Listen for minimize capability from the parent integration and wire mount sizing in code on the [Implementation](/web-sdk/minimized-layout/implementation) page.