Skip to main content

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.

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.
Minimized layout applies only to the headed Web SDK. It requires Web SDK 3.1.0 or later.

​
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.
StatusDescriptionAction
expandedThe full headed panel is active in your mount slot.Restore your usual width, height, min sizes, and flex rules for that region.
minimizedThe SDK is a small floating widget; ambient capture can still be active.Collapse or hide your mount wrapper so chart content can expand.
minimized-pausedThe SDK uses minimized chrome while ambient is paused.Collapse the host slot the same way you do for minimized.

​
How to implement minimized layout

1

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.
2

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).
3

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.
4

Restore dimensions when expanded

When layout returns to expanded, restore your normal CSS dimensions or flex basis for the headed panel.
5

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

​
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). 
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";
});
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.
Prefer class names, design tokens, or layout components instead of inline styles in production; the samples above show the state transition clearly.

​
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 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.
1

Enable the feature

To enable the feature for your organization, contact support.
2

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.
3

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.
4

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.
If you are unsure how minimize is enabled for staging or production, ask your Suki integration contact for the current rollout process.

​
Troubleshooting

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 to learn more about how to avoid this issue.
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.
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.
Last modified on May 22, 2026