Skip to main content

Edge groups

Edge groups are DockviewGroupPanel instances pinned to one of the four edges of the layout ('left', 'right', 'top', 'bottom'). They support tabs, drag-and-drop, overflow, and the full group panel API, and their state is included in toJSON / fromJSON.

Edge groups cannot be maximized or converted into floating/popout windows. They are structural elements of the layout.

The dndEdges prop controls the drag-and-drop overlay that appears when dragging panels to the far edges of the layout. See Drag and Drop for configuration details.

Adding edge groups​

Call addEdgeGroup in your onReady handler (or any time after initialization):

// JavaScript
dockview.addEdgeGroup('left', {
    id: 'left-group',
    initialSize: 220,
    minimumSize: 150,
});
dockview.addEdgeGroup('right', {
    id: 'right-group',
    initialSize: 220,
    minimumSize: 150,
});
dockview.addEdgeGroup('bottom', {
    id: 'bottom-group',
    initialSize: 200,
    minimumSize: 100,
});
// React
<DockviewReact
    onReady={(event) => {
        event.api.addEdgeGroup('left', {
            id: 'left-group',
            initialSize: 220,
            minimumSize: 150,
        });
        event.api.addEdgeGroup('bottom', {
            id: 'bottom-group',
            initialSize: 200,
            minimumSize: 100,
        });
    }}
    components={components}
/>

Calling addEdgeGroup for a position that is already registered throws an error.

Edge group options​

collapsed
collapsed?: boolean
collapsedSize
collapsedSize?: number
id
id: string
initialSize
initialSize?: number
maximumSize
maximumSize?: number
minimumSize
minimumSize?: number
autoHide
Opt this edge group in/out of auto-hide (pinnable tool-window) behaviour, overriding the global autoHideEdgeGroups option. Requires the auto-hide module to have any effect. Leave unset to inherit the global.
autoHide?: boolean
autoReveal
When true, this edge group tears itself down to zero footprint once emptied (instead of collapsing to a strip). This is the behaviour used by drag-revealed edges.
autoReveal?: boolean

Adding panels into an edge group​

Use addPanel with a position.referenceGroup pointing at the edge group's id:

const leftApi = api.addEdgeGroup('left', {
    id: 'left-group',
    initialSize: 220,
});

api.addPanel({
    id: 'explorer',
    component: 'Explorer',
    title: 'Explorer',
    position: { referenceGroup: leftApi.id },
});

API​

addEdgeGroup
Add an edge group at the given position. Returns the group panel API for the newly created group. Throws if a group already exists there.
addEdgeGroup(position: EdgeGroupPosition, options: AddEdgeGroupOptions): DockviewGroupPanelApi
getEdgeGroup
Get the group panel API for an edge group at the given position. Returns undefined if no edge group is configured at that position.
getEdgeGroup(position: EdgeGroupPosition): undefined | DockviewGroupPanelApi
isEdgeGroupVisible
Check whether an edge group is currently visible.
isEdgeGroupVisible(position: EdgeGroupPosition): boolean
removeEdgeGroup
Remove an edge group and reclaim its slot in the layout. All panels inside the group are disposed. Throws if no group exists at position.
removeEdgeGroup(position: EdgeGroupPosition): void
revealEdgeGroupWithData
Reveal (create-or-fill) the edge group at position and move the dragged item described by data into it. A newly created edge group tears down to zero footprint when later emptied. Drives the dock-to-edge groups behind the dockToEdgeGroups option; a no-op if edge groups are unavailable.
revealEdgeGroupWithData(position: EdgeGroupPosition, data: {
		groupId: string,
		panelId?: 'null' | string
	}, options: {
		autoHide?: boolean
	}): void
setEdgeGroupVisible
Set the visibility of an edge group.
setEdgeGroupVisible(position: EdgeGroupPosition, visible: boolean): void

Collapse and expand​

Edge groups can be collapsed to their header strip and expanded back to their last size programmatically, or by the user clicking the active tab.

  • Clicking the active tab toggles collapse/expand.
  • Clicking a non-active tab switches to that tab, and expands the group if it was collapsed.
  • Removing all panels from an edge group automatically collapses it.
onDidCollapsedChange
Fired when an edge group's collapsed state changes. Never fires for non-edge groups.
readonly onDidCollapsedChange: Event<DockviewGroupPanelCollapsedChangeEvent>
collapse
Collapse this group (edge groups only). No-op for non-edge groups.
collapse(): void
expand
Expand this group (edge groups only). No-op for non-edge groups.
expand(): void
isCollapsed
Returns true if this edge group is currently collapsed. Always returns false for non-edge groups.
isCollapsed(): boolean
const groupApi = api.getEdgeGroup('left');

groupApi?.collapse();
groupApi?.expand();
const isCollapsed = groupApi?.isCollapsed(); // boolean

The collapsedSize (the pixel height/width of the header when collapsed) defaults to 35px and can be configured per-group via EdgeGroupOptions.collapsedSize, or per-theme via DockviewTheme.edgeGroupCollapsedSize.

Themes that set a custom edgeGroupCollapsedSize:

ThemeedgeGroupCollapsedSize
themeVisualStudio22
themeAbyssSpaced44
themeGithubLightSpaced44
All other themes35 (default)

When an edge group loses all of its panels it is automatically collapsed. Adding a new panel to it will expand it again.

Collapsed edge groups can auto-hide and peek back on demand. See Auto-hide Edge Groups.

Dock to edge groups​

With the dockToEdgeGroups option an edge takes up zero space when empty and is revealed by dragging a panel to it, like a VS Code sidebar. See Dock to edge groups.

Auto-hide co-existence​

Auto-hide (the pinnable tool-window behaviour) is opt-in per edge group, so a static always-docked edge group and an auto-hiding one can co-exist in the same layout. Pass autoHide to addEdgeGroup, or toggle it at runtime with api.setAutoHide; either overrides the per-edge autoHideEdgeGroups option for that group. api.isAutoHide() reads the resolved value back: the per-group override if one is set, otherwise the autoHideEdgeGroups option for that edge.

// this edge group auto-hides; others follow the per-edge option
api.addEdgeGroup('left', { id: 'left-group', autoHide: true });

// toggle at runtime
api.getEdgeGroup('right')?.setAutoHide(true);

// read the resolved state (per-group override, else the global option)
const autoHides = api.getEdgeGroup('right')?.isAutoHide(); // boolean

Turning auto-hide off on a group that is currently collapsed leaves a strip with no way to open it: the click-to-peek trigger goes away with auto-hide and the sash is locked at the collapsed size. Call expand() alongside setAutoHide(false) if the group might be collapsed.

Custom header actions​

The location prop in rightHeaderActionsComponent, leftHeaderActionsComponent, and prefixHeaderActionsComponent updates reactively when a group moves. Use it to show controls specific to edge groups.

The DockviewGroupLocation type is a discriminated union:

type DockviewGroupLocation =
    | { type: 'grid' }
    | { type: 'floating' }
    | { type: 'popout'; getWindow: () => Window }
    | { type: 'edge'; position: EdgeGroupPosition }; // 'top' | 'bottom' | 'left' | 'right'

Check location.type to distinguish edge groups, and location.position to know which edge:

DockviewGroupLocation is exported from all framework packages.

See Group Controls for the full header actions reference.

Serialization​

Edge group state (size, visibility, collapsed state, and panel contents) is included in toJSON / fromJSON automatically.

On fromJSON, edge groups are auto-created for any positions present in the serialized state that were not pre-registered via addEdgeGroup, so restoring a saved layout works without calling addEdgeGroup first:

const state = api.toJSON();
// state.edgeGroups = {
//   left:   { size: 220, visible: true,  collapsed: false, group: { ... } },
//   bottom: { size: 200, visible: false, collapsed: false, group: { ... } },
// }

api.fromJSON(state); // auto-creates and restores edge groups

See also​