Floating Groups

This section describes floating groups.

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

Dockview has built-in support for floating groups. Each floating container hosts its own nested layout, so you can dock multiple groups together inside a single floating container, and you can have as many floating containers as needed.

Options

The following properties can be set to configure the behaviours of floating groups.

You can control the bounding box of floating groups through the optional floatingGroupBounds options:

• boundedWithinViewport will force the entire floating group to be bounded within the docks viewport.
• {minimumHeightWithinViewport?: number, minimumWidthWithinViewport?: number} sets the respective dimension minimums that must appears within the docks viewport
• If no options are provided the defaults of 100px minimum height and width within the viewport are set.

Drag handle

floatingGroupDragHandle selects which element moves a floating group when dragged:

• 'titlebar' (default): a dedicated, blank drag-handle bar is rendered above the group's tab bar. Dragging it moves the floating window; shift+drag (mouse) or long-press (touch) redocks the group back into the grid. Style it with the --dv-floating-titlebar-* theme variables.
• 'tabbar': the legacy behaviour — the empty space in the tab bar (the "void container") doubles as the move handle, with no dedicated bar rendered.

const api = createDockview(element, {
    floatingGroupDragHandle: 'titlebar', // the default
});

Customising drag behaviour

transformFloatingGroupDrag lets you adjust a floating group's position while it is being dragged — for snapping to a grid, aligning to other floating groups, or constraining a group to a region. It runs on every pointer-move frame with the proposed top-left (before dockview's container clamp) and returns an adjusted top-left, or nothing to leave it unchanged. It affects moving only — resizing is unaffected.

const api = createDockview(element, {
    // …
    transformFloatingGroupDrag: ({ group, proposed, container, others }) => {
        // Snap the proposed position to a 20px grid
        return {
            top: Math.round(proposed.top / 20) * 20,
            left: Math.round(proposed.left / 20) * 20,
        };
    },
});

context.others holds the bounds of the other floating groups (relative to the same container), snapshotted at drag start, so you can align the dragged group against its siblings.

API

The following properties can be used to create floating groups

addFloatingGroup	Add a floating group addFloatingGroup(item: DockviewGroupPanel | IDockviewPanel, options: FloatingGroupOptions): void

addFloatingGroup only accepts existing panels and groups. See Addding Panels on how to firstly add panels.

Floating groups can be programatically added through the dockview api method api.addFloatingGroup(...).

Panel and Group API

location	readonly location: DockviewGroupLocation
onDidLocationChange	readonly onDidLocationChange: Event<DockviewGroupPanelFloatingChangeEvent>

You can check whether a group is floating via the group.api.location property. See examples for full code.

Working with Floating Groups

Float an existing tab by holding shift whilst interacting with the tab

Move a floating tab by holding shift whilst moving the cursor or dragging the empty header space

Move an entire floating group by holding shift whilst dragging the empty header space

Live Example