Skip to main content

Managing groups

This page covers creating, removing, and clearing groups programmatically.

Adding a group​

api.addGroup() creates an empty group and returns it. You can position it relative to an existing panel or group, or at an absolute edge of the layout.

addGroup
Add a group and return the created object.
addGroup(options: AddGroupOptions): DockviewGroupPanel
// Add a group to the right edge of the layout
const group = api.addGroup({ direction: 'right' });

// Add a group relative to an existing panel
const group = api.addGroup({
    referencePanel: 'panel_1',
    direction: 'below',
});

// Add a group relative to another group
const group = api.addGroup({
    referenceGroup: existingGroup,
    direction: 'left',
});

Once you have a group reference you can add panels into it:

const group = api.addGroup({ direction: 'right' });

api.addPanel({
    id: 'panel_1',
    component: 'default',
    position: { referenceGroup: group },
});

Serializing a single group​

api.serializeGroup() captures one group together with the state of every panel it holds, as a self-contained object. api.addGroupFromJSON() rebuilds that group into a live layout, positioned as for addGroup, without touching the rest of the layout. Together they move a group between two layouts, or between two Dockview instances, where fromJSON would replace the whole layout.

addGroupFromJSON
Rebuild a group from serializeGroup output and add it to the live layout, positioned as for addGroup, leaving the rest of the layout untouched. Throws before changing anything if a panel id is already in use.
addGroupFromJSON(data: SerializedDockviewGroup, options: AddGroupFromJSONOptions): DockviewGroupPanel
serializeGroup
Serialize one group together with the state of every panel it holds. The result is self-contained and can be rehydrated with addGroupFromJSON, on this instance or another one.
serializeGroup(group: IDockviewGroupPanel): SerializedDockviewGroup
// In the source instance
const data = sourceApi.serializeGroup(group);
sourceApi.removeGroup(group);

// In the target instance, which may live in another window or process
const moved = targetApi.addGroupFromJSON(data, {
    referenceGroup: targetApi.activeGroup,
    direction: 'right',
});

The serialized object carries the group's tab order, active tab, locked state, header position and tab groups, plus each panel's component, title, parameters, renderer and size constraints. It does not carry the group's size, which only has meaning in the grid it came from: the placement decides the size in the new layout.

A reference group or panel with direction: 'within', or with no direction, merges the serialized panels into that group instead of creating one, in their order and at index if given, as addPanel does. The serialized group's own shape does not apply then. This is what a drop on a group's centre or tab bar calls for (both report position: 'center'), and the only form that works against a floating or edge group, which has no grid neighbours:

targetApi.onDidDrop((event) => {
    if (event.group && event.position === 'center') {
        targetApi.addGroupFromJSON(data, {
            referenceGroup: event.group,
            direction: 'within',
            index: event.index,
        });
    }
});

A single tab travels as panel.toJSON() and lands with addPanelFromJSON, which places it as addPanel would (a position, or floating) and takes the drop index the same way:

targetApi.addPanelFromJSON(state, {
    position: { referenceGroup: event.group, index: event.index },
});
addPanelFromJSON
Add a panel from its toJSON() state, placed as addPanel places one: the counterpart to panel.toJSON() for a single tab moving between layouts or instances, as addGroupFromJSON is to serializeGroup. Throws before changing anything if the panel id is already in use.
addPanelFromJSON(state: GroupviewPanelState, options: AddPanelFromJSONOptions): IDockviewPanel

Panel ids must be unique within the receiving instance. addGroupFromJSON throws before changing anything if a panel id is already in use, as addPanel does. A group id that is already in use is reassigned with a warning, as addGroup does, so give groups unique ids when they move between instances.

By default every instance numbers its groups from "1", so two instances collide on nearly every move. The groupIdGenerator option replaces that counter for every group Dockview creates on its own, so ids can be unique across instances. Dockview only asks for a fresh id and retries one that is already in use; how the id is made is yours to choose:

const api = createDockview(element, {
    groupIdGenerator: () => crypto.randomUUID(),
    // ...
});

Panel ids are always yours to choose, so the same generator serves there too.

Removing a group​

api.removeGroup() removes a group and all panels it contains.

removeGroup
Remove a group and any panels within the group.
removeGroup(group: IDockviewGroupPanel): void
const group = api.activeGroup;
if (group) {
    api.removeGroup(group);
}

You can also close a group through the group API itself:

panel.group.api.close();

Closing all groups​

api.closeAllGroups() removes every group and panel from the layout, leaving it empty.

closeAllGroups
Close all groups and panels.
closeAllGroups(): void
api.closeAllGroups();

Clearing the layout​

api.clear() resets the component back to a completely empty, default state. It is equivalent to closeAllGroups() but also resets any internal state.

api.clear();

Use api.clear() before calling api.fromJSON() to guarantee a clean starting point. Alternatively, fromJSON accepts a reuseExistingPanels option:

api.fromJSON(layout, { reuseExistingPanels: true });

See also​