Skip to main content

Multi-row tabsEnterprise

When a group accumulates more tabs than fit across the width of its header, the default behaviour is to collapse the surplus behind an overflow dropdown. Multi-row tabs offer an alternative: the strip wraps onto additional rows and the header grows to fit, so every tab stays visible at once. The default single-row dropdown behaviour is covered in Tab Overflow.

Multi-row (wrapping) tabs​

Set overflow.mode: 'wrap' and, instead of clipping the surplus tabs into the dropdown, the tab strip wraps onto additional rows and the header grows to fit, a JetBrains-style layout where every tab stays visible at once. As tabs are added or removed, the header grows and shrinks by whole rows, and the panel content area resizes to match.

maxRows
Wrap mode only: cap the number of header rows. The strip grows to at most maxRows rows; tabs that would land on a row beyond the cap spill into the overflow dropdown instead. Requires the MultiRowTabsModule. Default: unbounded (wrap grows to fit every tab).
maxRows?: number
mode
What happens when tabs don't fit. Default 'dropdown' (today's free path). 'wrap' requires the MultiRowTabsModule.
mode?: 'wrap' | 'dropdown'
mru
Order the dropdown by most-recently-activated. Reserved for AdvancedOverflowModule; ignored until present. Default: false.
mru?: boolean
search
Filter input over the group's tabs. Reserved for AdvancedOverflowModule; ignored until that module is present. Default: false.
search?: {
placeholder?: string,
scope?: 'group' | 'overflow'
} | boolean

overflow.mode: 'wrap' is an enterprise feature. With dockview-enterprise imported it is enabled for every Dockview instance; without it, mode: 'wrap' is ignored and the standard single-row strip with the dropdown is used instead; no error, no regression.

maxRows​

overflow.maxRows caps how many rows the header may grow to. The strip wraps up to maxRows rows; any tab that would land on a row beyond the cap spills into the chevron overflow dropdown instead, so wrapping and the dropdown compose rather than conflict. Left unset, wrapping is unbounded and the header grows to fit every tab.

const api = createDockview(element, {
    overflow: { mode: 'wrap', maxRows: 2 },
});

// raise or lower the cap at runtime and the strip reflows
api.updateOptions({ overflow: { mode: 'wrap', maxRows: 3 } });

maxRows is part of the same enterprise multi-row tabs feature as mode: 'wrap', so it is only honoured in wrap mode; it has no effect on the single-row dropdown.

Reordering across rows​

Tabs can be dragged to reorder them just as in the single-row strip, and in wrap mode the reorder is two-dimensional: you can drag a tab from one row onto another and drop it at any position, with a drop indicator showing where it will land. Dragging a tab out of the header to detach or float it works exactly as before.

Vertical (column) wrapping​

Wrapping applies to vertical headers too. When a group's header sits on the left or right (for example an edge group), the tabs wrap into additional columns and the header grows in width rather than height, and maxRows becomes a maximum column cap. A change of header direction at runtime is handled automatically, so a group that flips between a horizontal and a vertical header re-wraps to match.

Advanced overflow​

The overflow block also carries search and mru fields that turn the dropdown into a searchable, most-recently-used tab switcher. Both are part of the enterprise advanced overflow feature. These compose with wrap mode: tabs that spill past maxRows land in the same enhanced dropdown. See Advanced overflow.

See also​

  • Tab overflow: the default single-row dropdown this mode replaces.
  • Advanced overflow: search and most-recently-used ordering for the dropdown.
  • Pinned tabs: another way to keep important tabs visible.
  • Tab header position: wrapping applies to horizontal and vertical headers, filling extra rows or columns respectively.