Skip to main content

Smart guidesEnterprise

Smart Guides bring Figma / Keynote-style alignment guides and magnetic snapping to Dockview's floating groups. While you drag a floating group, Dockview draws crisp alignment lines and gently snaps the dragged group when one of its edges or centres lines up with another floating group, the container, or (optionally) the grid splitters behind it.

Smart Guides apply to floating groups only. Docked groups in the grid are unaffected, and no guides are shown when dragging them.

Enable Smart Guides through the smartGuides option. Omit it entirely to leave floating-group dragging unchanged.

Drag one of the floating groups towards the other, or towards a container edge, to see the alignment guides appear and the group snap into place. Hold Alt while dragging to move freely without snapping.

Options​

The smartGuides option accepts a SmartGuidesOptions object:

className
Extra class applied to the guide overlay layer, for theming.
className?: string
disableSnapModifier
Hold this modifier while dragging to temporarily suspend snapping + guides (Figma/Keynote parity). false disables the gate. Default 'alt'.
disableSnapModifier?: SnapModifier | 'false'
enabled
Master switch. Defaults to true when smartGuides is present.
enabled?: boolean
releaseDistance
Extra px beyond snapDistance the pointer must travel before an engaged snap releases; asymmetric hysteresis that stops boundary oscillation. Default 4.
releaseDistance?: number
showGuides
Render the alignment guide lines while snapping. Default true.
showGuides?: boolean
snapDistance
Distance, in px, within which a dragged edge/center engages a snap. Default 8.
snapDistance?: number
snapTargets
Which alignment sources to snap against (floats + container by default).
snapTargets?: SmartGuidesSnapTargets
snapTogether
Detect a dock/merge intent when the dragged float comes flush against another float (edge-adjacency) or overlaps its tab strip (tabset merge), and commit it on drop. Opt-in: Smart Guides is an alignment-only tool by default and never merges floating groups unless this is set. Default false.
snapTogether?: boolean
const api = createDockview(element, {
    smartGuides: {
        snapDistance: 8,
    },
});

How snapping works​

  • Alignment. As a floating group is dragged, its leading edge, centre, and trailing edge on each axis are compared against the alignment lines contributed by the other floating groups and the container. When a probe lands within snapDistance of a line, the group snaps so the two align exactly, and a guide line is drawn.
  • Independent X and Y. The horizontal and vertical axes are resolved independently; a group can snap horizontally to one neighbour and vertically to another at the same time, drawing a guide for each alignment.
  • Hysteresis. To avoid the group "sticking then jumping" at the snap boundary, a snap engages at snapDistance but only releases once the pointer moves past snapDistance + releaseDistance. This asymmetric threshold keeps snapping stable and stops oscillation.
  • Guides. Set showGuides: false to keep the magnetic snapping behaviour but hide the alignment lines.

Snap targets​

Choose which sources a dragged floating group aligns against with snapTargets:

container
Align to the container's edges + center. Default true.
container?: boolean
containerInset
Also emit inset guide lines this many px inside the container edges (e.g. a content margin). Default undefined (no inset lines).
containerInset?: number
floats
Align to the other floating groups' edges + centers. Default true.
floats?: boolean
splitters
Align to the underlying grid's splitter (sash) positions. Default false.
splitters?: boolean
  • floats (default true): align to the other floating groups' edges and centres.
  • container (default true): align to the container's edges and centre. Set containerInset to also emit guide lines a fixed number of pixels inside the container edges (e.g. a content margin).
  • splitters (default false): align to the underlying grid's splitter (sash) positions, so a floating group can line up with the docked layout behind it.
const api = createDockview(element, {
    smartGuides: {
        snapTargets: {
            floats: true,
            container: true,
            containerInset: 16,
            splitters: true,
        },
    },
});

Snap-together (dock / merge)​

By default Smart Guides is an alignment tool only: it aligns and snaps floating groups but never docks or merges them. Set snapTogether: true to opt in, and Smart Guides also detects a dock or merge intent while dragging:

  • Dragging a floating group flush against another group's opposite edge (with sufficient perpendicular overlap) suggests docking it beside the target.
  • Dragging a floating group so its tab strip overlaps another's suggests merging the two into a shared tabset (a center drop).

A drop preview is shown during the drag, and the dock/merge is committed on drop.

const api = createDockview(element, {
    smartGuides: {
        // Opt in to dock/merge suggestions (off by default)
        snapTogether: true,
    },
});

Disabling snapping mid-drag​

Hold the configured modifier key while dragging to temporarily suspend snapping and hide the guides; the floating group then follows the pointer freely (Figma / Keynote parity). Snapping re-engages as soon as the modifier is released.

The modifier defaults to Alt and is configured via disableSnapModifier ('alt' | 'ctrl' | 'meta' | 'shift', or false to remove the gate entirely).

const api = createDockview(element, {
    smartGuides: {
        // Hold Ctrl to drag without snapping
        disableSnapModifier: 'ctrl',
    },
});

A single floating group can be excluded from Smart Guides entirely by passing disableSmartGuides: true when creating it (for example a pinned HUD that should never snap). See api.addFloatingGroup(...).

Runtime control​

Smart Guides can be toggled and reconfigured at runtime through the api:

smartGuidesEnabled
Whether Smart Guides snapping is active (the smartGuides option is present + enabled and the module is registered). Reactive via setSmartGuidesEnabled.
smartGuidesEnabled: boolean
setSmartGuidesEnabled
Toggle Smart Guides snapping at runtime (no-op when the module is absent).
setSmartGuidesEnabled(enabled: boolean): void
updateSmartGuidesOptions
Merge a partial Smart Guides option override in at runtime.
updateSmartGuidesOptions(options: Partial<SmartGuidesOptions>): void
// Toggle snapping without removing the option
api.setSmartGuidesEnabled(false);

// Merge in a partial option override
api.updateSmartGuidesOptions({ snapDistance: 12 });

Events​

Two events fire when a drag commits on drop:

onDidSnapFloat
Fires when a dragged floating group commits an alignment snap on drop.
onDidSnapFloat: Event<SmartGuidesSnapEvent>
onDidSnapTogether
Fires when a dragged floating group docks/merges into another on drop.
onDidSnapTogether: Event<SmartGuidesSnapTogetherEvent>
  • onDidSnapFloat: fires when a dragged floating group commits an alignment snap on drop, reporting which axes ('x' / 'y') were snapped.
  • onDidSnapTogether: fires when a dragged floating group docks or merges into another on drop, reporting the target group and the position ('left' | 'right' | 'top' | 'bottom' | 'center').
api.onDidSnapFloat((event) => {
    console.log('snapped on axes', event.axes);
});

api.onDidSnapTogether((event) => {
    console.log(
        'docked',
        event.dragged.id,
        event.position,
        'of',
        event.target.id
    );
});

See also​