Popout windows

Popout groups open a group in a separate native browser window while it stays part of the same Dockview layout, useful for spreading panels across multiple monitors. The group can be docked back into the grid at any time.

Popout groups cannot be maximized. Calling maximize function on groups in these states will have no effect.

addPopoutGroup	Add a popout group in a new Window addPopoutGroup(item: DockviewGroupPanel | IDockviewPanel, options: DockviewPopoutGroupOptions): Promise<boolean>

Dockview has built-in support for opening groups in new windows. Each popout window hosts its own nested layout, so you can dock multiple groups together inside a single popout window, and you can have as many popout windows as needed.

The popout lifecycle is observable: onDidAddPopoutGroup / onDidRemovePopoutGroup fire as windows open and close (or dock back), and api.getPopouts() enumerates the open popout windows. See Events.

Popout windows require your website to have a blank .html page that can be used, by default this is set to /popout.html but can be configured to match requirements.

api.addPopoutGroup(
    group,
    // the second arguments (options) is optional
    {
        popoutUrl: '/popout.html',
        box: { left: 0, top: 0, height: 200, width: 300 },
    }
);

If you do not provide options.popoutUrl a default of /popout.html is used and if options.box is not provided the panel will be placed according to its current position.

popoutUrl must point to a same-origin http(s) location. Dockview rejects javascript:, data:, blob:, and cross-origin URLs to prevent a malicious value (for example, from a layout JSON loaded from an untrusted source) from executing script in a context the browser still associates with your application via window.opener. The guard runs automatically when the popout is opened, including on layouts restored via fromJSON().

From within a panel you may say

props.containerApi.addPopoutGroup(props.api.group);

Closing the popout group

To programmatically move the popout group back into the main grid you can use the moveTo method in many ways, one of the following would suffice

// option 1: add absolutely to the right-side of the grid
props.group.api.moveTo({ position: 'right' });

// option 2: create a new group and move the contents of the popout group to it
const group = props.containerApi.addGroup();
props.group.api.moveTo({ group });

Alternatively, if the user closes the window the group Dockview will make a best attempt to place it back in its original location within the grid. If Dockview cannot determine the original location it will choose a new location.

Overlays inside popout windows

Floating overlays, including drag-target indicators, the tab context menu, and tab group chip popovers (color picker, rename), render inside the DOM of the window that hosts them. When a group lives in a popout window, those overlays render in the popout window's document, not the parent. This means:

• Custom chip components and context menu components are mounted in the popout window's DOM tree.
• CSS that you load into the main page is automatically copied into popout windows; if you ship custom styles outside the standard import pipeline (for example, lazily injected stylesheets), make sure they are also available in the popout window.
• Event handlers and portals inside custom components should not assume the document is the main window; use the element's ownerDocument when you need a reference.

Popout window events

DockviewApi exposes three events specific to popout windows:

// Fires when the popout window is resized by the user
api.onDidPopoutGroupSizeChange((event: PopoutGroupChangeSizeEvent) => {
    console.log('popout resized:', event);
});

// Fires when the popout window is moved by the user
api.onDidPopoutGroupPositionChange((event: PopoutGroupChangePositionEvent) => {
    console.log('popout moved:', event);
});

// Fires when the browser blocked opening the popout window (e.g. popup blocker)
api.onDidOpenPopoutWindowFail(() => {
    alert('Please allow popups for this site to use this feature.');
});

See also

• Floating groups: float a group above the grid without a separate window
• Events: observe the popout window lifecycle
• Security: same-origin requirements and CSP for popout windows