Interface DockviewOptions

Built-in screen-reader announcements of layout changes (a visually-hidden aria-live region narrating panel open/close etc.). On by default; set to false to disable, e.g. when the host app provides its own announcement system. Honoured live via updateOptions.

Route announcements to your own screen-reader infrastructure instead of the built-in aria-live regions (e.g. an app-wide live region). When set, dockview hands you each AnnouncementEvent and writes nothing to its own regions. getAnnouncement (localisation) still applies first.

VS Code-style "auto hide" for edge groups: render clickable activators in a collapsed edge group's strip so it can be pinned back. Off by default → today's baseline (an empty collapsed strip) is unchanged.

A per-edge set: true applies to all four edges, or name edges individually ({ left: true, bottom: true }). An edge group at an edge not in the set stays a static collapsing sidebar. A per-group api.setEdgeGroupAutoHide() override wins over this default. Peek animation is tuned globally via edgeGroupPeek.

Factory to create the custom ghost element shown while dragging a group of panels (the small floating chip that follows the cursor).

If not provided, a default ghost rendering "Multiple Panels (N)" is used. Supplying a factory replaces the entire default ghost, enabling i18n / custom visuals.

Factory to create custom tab group chip renderers. If not provided, the default chip renderer is used.

Disable the auto-resizing which is controlled through a ResizeObserver. Call .layout(width, height) to manually resize the container.

Show an aim-at-a-cell DnD compass over a group while dragging, instead of resolving the drop by which quadrant the cursor is in. Default off ⇒ the cursor-quadrant behaviour, unchanged. Provided by the DnD compass module. Pass an object to restrict which inner cells appear (zones) or to hide the outer whole-layout-edge cells (edges: false, default on).

Selects which drag-and-drop implementation is active.

• 'auto' (default): HTML5 drag-and-drop drives mouse drags; pointer events drive touch and pen drags. Matches the historical behaviour.
• 'pointer': pointer events drive every input type. Useful in environments where HTML5 drag-and-drop is unreliable (some Linux browsers, certain Safari versions, embedded webviews). Cross-window HTML5 drag and the HTML5 native drag image are not available in this mode.
• 'html5': HTML5 drag-and-drop only; disables touch / pen drag.

Let panels dragged to a layout edge create/fill an edge group that is invisible when empty (VS Code-style "drag a panel to the far edge → new sidebar"). Created on drop; torn down to zero footprint when its last panel leaves.

A per-edge set: true enables dock-to-edge on all four edges, or name edges individually. Off by default.

Requires the AutoEdgeGroup module (and the EdgeGroup module it builds on); a no-op if absent, where a root-edge drop splits the grid as usual. Distinct from dndEdges, which only shapes the outer drop overlay (and still splits the grid).

Shape the drop overlay shown over a group's drop targets: the tab strip ('tab'), the header void space ('header_space') and the panel content area ('content'). Return a DroptargetOverlayModel to override that target's default overlay (size, activation threshold, small-element boundaries), or undefined to keep the default.

group is provided where known (tab / header_space). The outer-layout edge overlay is shaped by dndEdges, not this option, so 'edge' is not dispatched here.

Override how a pointer location maps to a drop Position (or null for no drop) on the 5-way group/layout drop targets (the group content and the whole-layout edges), replacing the built-in cursor-quadrant logic. Tab/header reorder targets are unaffected. Unset ⇒ the default quadrant behaviour, unchanged. Read live, so it can be swapped via DockviewApi.updateOptions.

Peek interaction tuning for autoHideEdgeGroups (global, not per-edge).

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) / long-press (touch) redocks into the grid. Style it with the --dv-floating-titlebar-* theme variables.
• 'tabbar': the legacy behaviour, where the empty space in the tab bar (the "void container") doubles as the move handle. No dedicated bar is rendered.

Localise or override the built-in announcement strings (the default messages are English). Return a string to use it, null / '' to suppress that announcement, or undefined to keep the default. This is how non-English apps translate announcements; core ships no message catalog, only the default strings + this hook.

Return the items to display in the tab context menu on right-click.

Use built-in string shortcuts or provide a ContextMenuItemConfig object for custom items. The available shortcuts are:

• 'close': close this panel
• 'closeOthers': close every other panel in the group
• 'closeAll': close every panel in the group
• 'closeLeft' / 'closeRight': close the panels before / after this one in the tab strip
• 'maximize': maximize the group (renders as Restore and disables for non-grid panels, tracking the group's live maximized state)
• 'float': move the panel into a floating window (disabled when already floating)
• 'popout': move the panel into a new browser window (disabled when already popped out)
• 'pin': toggle the panel's pinned state (PinnedTabs module)
• 'separator': a divider line

If omitted, no context menu is shown. Return an empty array to suppress the menu for specific cases.

Return the items to display in the tab group chip context menu on right-click.

Use built-in string shortcuts or provide a ContextMenuItemConfig object for custom items. The available shortcuts are:

• 'rename': renders an inline text input to rename the tab group
• 'colorPicker': renders a grid of color swatches for the tab group
• 'collapse': collapse the tab group (renders as Expand when the group is already collapsed)
• 'close': close every panel belonging to the tab group
• 'separator': a divider line

If omitted, no context menu is shown on chip right-click. Return an empty array to suppress the menu for specific cases.

Operate the dock with the keyboard. true enables the default bindings; pass an object to override individual ones via keymap. Off by default (opt-in while the feature matures). Enables:

• Switch tab within the focused group: Ctrl+] / Ctrl+[.
• Move focus between groups: F6 / Shift+F6 (sequential) or Ctrl+Shift+arrow keys (spatial: focus the group in that direction).
• Dock the active panel without a mouse: Ctrl+M arms a two-phase move (arrows cycle the target group with a live drop preview + screen-reader narration, Enter docks, Escape cancels).

Defaults avoid Cmd-based and browser-reserved combinations (e.g. Cmd+M is the macOS minimise-window shortcut); use keymap to rebind for your platform.

Undo / redo for layout mutations (close / move / float / popout / add / maximize / tab-group changes). Off by default; set { enabled: true } to record. Drive it via api.undo() / api.redo(); dockview binds no keys itself (that's the host app's call, and collides with the keyboard navigation keymap). Honoured live via updateOptions.

Translate / override the strings dockview speaks to assistive technology, covering both the LiveRegion announcements and the keyboard-docking narration. Provide any subset of DockviewMessages; unset entries keep the English defaults. (getAnnouncement still applies first, per-event, for announcements.)

Define the behaviour of the dock when there are no panels to display. Defaults to watermark.

How the tab header behaves when there are more tabs than fit on one row.

The single-row strip + chevron dropdown is the default and is free. The 'wrap' mode (tabs wrap onto multiple rows and the header grows) requires the MultiRowTabsModule; without that module 'wrap' is ignored and the dropdown is used. The search/mru fields enrich the dropdown and require the AdvancedOverflowModule; they are ignored when that module is absent.

Omitting overflow is identical to today's behaviour (mode: 'dropdown').

Pin tabs so they render before all unpinned tabs in their group, never overflow into the dropdown, and resist reorder across the pin boundary. Modelled on VS Code / Chrome pinned tabs. Owned by the PinnedTabs module; dormant unless enabled is set.

Select native to use built-in scrollbar behaviours and custom to use an internal implementation that allows for improved scrollbar overlay UX.

This is only applied to the tab header section. Defaults to custom.

Enable Smart Guides: alignment guides + magnetic snapping while a floating group is being dragged. Omit to disable entirely (float dragging is then unchanged). Provided by the Smart Guides module.

Controls how dockview applies tab group color accents.

• 'palette' (default): write --dv-tab-group-color, render the color picker, and apply built-in accent styling.
• 'off': opt out entirely. No --dv-tab-group-color is written, the color picker is suppressed, and chips/indicators render without the accent. The tg.color data field is preserved so custom chip renderers can still read it and roll their own visual.

Replace the built-in tab group color palette with a user-defined list.

Each entry has an id (stored on tabGroup.color and serialized), a value (any CSS color expression: hex, rgb(), var(...), etc.), and an optional label shown in the context menu picker.

If omitted, the default 9-color palette is used. The list fully replaces the defaults; there is no merge.

Adjust a floating group's position while it is being dragged. Runs on each pointer-move frame with the proposed top-left (before the container clamp) and returns an adjusted top-left, or nothing to leave it unchanged. Use it for snapping, alignment, or custom bounds. Move only: resizing a floating group is unaffected.

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