react-zeugma

A recursive, drag-and-drop dashboard layout engine for React. It combines the tree-based, arbitrary splitting capabilities of react-mosaic with the declarative, state-driven API model of react-grid-layout, powered by @dnd-kit/core.

It is completely style-agnostic (headless), meaning you style all container states, resizers, and drop previews with your own class names.

Installation

npm install react-zeugma

Quick Start

Initialize your layout tree with useZeugma and render the dashboard using <Zeugma>.

import { useZeugma, Zeugma, Pane, TreeNode } from 'react-zeugma'

// 1. Define the initial layout tree structure
const initialLayout: TreeNode = {
  type: 'split',
  direction: 'row',
  splitPercentage: 30,
  first: { type: 'pane', id: 'left-panel', tabs: ['left-panel'], activeTabId: 'left-panel' },
  second: { type: 'pane', id: 'right-panel', tabs: ['right-panel'], activeTabId: 'right-panel' },
}

// 2. Build your custom pane wrapper
function DashboardPane({ id }: { id: string }) {
  return (
    <Pane id={id}>
      <div className="flex flex-col h-full bg-zinc-900 border border-zinc-700">
        <Pane.DragHandle className="p-2 bg-zinc-800 cursor-grab text-zinc-300 font-semibold">
          {id}
        </Pane.DragHandle>
        <Pane.Content className="flex-1 p-4 text-zinc-400">
          {(tab) => <div>Active Tab Content: {tab.id}</div>}
        </Pane.Content>
      </div>
    </Pane>
  )
}

// 3. Mount the layout controller and dashboard renderer
export default function DashboardApp() {
  const controller = useZeugma({ initialLayout })

  return (
    <div className="w-screen h-screen">
      <Zeugma controller={controller} renderPane={(paneId) => <DashboardPane id={paneId} />} />
    </div>
  )
}

API Reference

Components

<Zeugma>

The root provider and layout renderer. It configures the drag-and-drop context, calculates panel positions, and renders resize splitters.

Usage

import { Zeugma } from 'react-zeugma'
;<Zeugma
  controller={controller}
  renderPane={(paneId) => <MyPane id={paneId} />}
  resizerSize={4}
  dragActivationDistance={8}
  snapThreshold={8}
  minSplitPercentage={5}
  maxSplitPercentage={95}
  enableDragToDismiss={false}
  dismissThreshold={60}
  classNames={{
    dashboard: 'bg-zinc-950',
    pane: 'rounded-lg overflow-hidden',
    resizer: 'bg-zinc-800 hover:bg-indigo-500 transition-colors',
    dropPreview: 'bg-indigo-500/20 border border-indigo-500',
  }}
  onRemove={(paneId) => console.log(`Pane ${paneId} closed`)}
  onResizeEnd={(currentNode, percentage) => console.log('Resized to', percentage)}
/>

Props

| Property | Description | Type | Default | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | controller | The layout state controller returned by useZeugma(options). | ZeugmaController | - | | children | Children components rendered inside the context provider. | ReactNode | - | | renderPane | Callback function to map active pane IDs to custom pane structures. Required in standalone mode (without children) and must not be passed in provider mode. | (paneId: string) => ReactNode | - | | renderDragOverlay | Custom overlay renderer function for the drag-under-cursor preview. | (active: DragOverlayActiveItem) => ReactNode | - | | classNames | CSS class name mapping overrides for custom dashboard and overlay styling. | ZeugmaClassNames | - | | resizerSize | Thickness of the split resizer bars in pixels. | number | 4 | | dragActivationDistance | Minimum pointer drag distance (in pixels) required to activate dragging. | number | 8 | | snapThreshold | Threshold in pixels to snap layout resizers to adjacent edges. | number | 8 | | minSplitPercentage | Minimum split limit percentage allowed for resized panes. | number | 5 | | maxSplitPercentage | Maximum split limit percentage allowed for resized panes. | number | 95 | | enableDragToDismiss | Enables drag-out-to-dismiss gesture for widgets. | boolean | false | | dismissThreshold | Distance in pixels outside container bounds required to trigger dismissal. | number | 60 | | onRemove | Callback triggered when a pane is removed. | (paneId: string) => void | - | | onDragStart | Callback triggered when a drag gesture begins. | (activeId: string) => void | - | | onDragEnd | Callback triggered when a drag gesture ends, containing active pane, target pane, and action metadata. | (activeId: string, overId: string \| null, dropAction: { type: 'split' \| 'move'; direction?: SplitDirection; position?: 'top' \| 'bottom' \| 'left' \| 'right' \| 'center' } \| null) => void | - | | onResizeStart | Callback triggered when resizing begins. | (currentNode: SplitNode) => void | - | | onResize | Callback triggered during pane resizing. | (currentNode: SplitNode, percentage: number) => void | - | | onResizeEnd | Callback triggered when pane resizing completes. | (currentNode: SplitNode, percentage: number) => void | - | | onDismissIntentChange | Callback triggered when drag-out dismiss intent changes. | (paneId: string \| null) => void | - | | persist | Layout persistence configuration in localStorage. If true, uses default options. | boolean \| ZeugmaPersistOptions | false |

ZeugmaPersistOptions

interface ZeugmaPersistOptions {
  /** Whether layout persistence is enabled. Defaults to true if this configuration object is provided. */
  enabled?: boolean
  /** The key used for localStorage persistence. Defaults to 'zeugma-layout'. */
  key?: string
}

<PaneTree>

Recursively renders the dashboard grid hierarchy (resizers, split panels, and active pane contents). Must be rendered when using <Zeugma> as a context provider.

Usage

import { Zeugma, PaneTree } from 'react-zeugma'
;<Zeugma controller={controller}>
  <div className="workspace">
    <PaneTree renderPane={(paneId) => <MyPane id={paneId} />} />
  </div>
</Zeugma>

Props

| Property | Description | Type | Default | | --------------- | ----------------------------------------------------------------------------------------- | ------------------------------- | ------- | | renderPane | Required. Callback function mapping unique pane IDs to custom <Pane> components. | (paneId: string) => ReactNode | - | | tree | Optional layout subtree to render (defaults to the root layout tree from the controller). | TreeNode \| null | - | | resizerSize | Optional override for the thickness of split resizer handles in pixels. | number | 4 | | snapThreshold | Optional override for the snapping threshold of resizer handles in pixels. | number | 8 |

<Pane>

Wraps each individual pane/widget within the dashboard, establishing drag-and-drop boundaries.

• <Pane.DragHandle>: Defines the interactive header or area used to drag the pane.
• <Pane.Content>: Renders the active tab's content. Accepts a child render function (tab) => React.ReactNode or static ReactNode.
• <Pane.Controls>: Renders standard control buttons for closing or maximizing the pane.

Usage

import { Pane } from 'react-zeugma'
;<Pane id="pane-1" locked={false}>
  <Pane.DragHandle className="p-2 cursor-grab bg-zinc-800">
    <span>Pane Title</span>
  </Pane.DragHandle>
  <Pane.Controls />
  <Pane.Content className="p-4">
    {(tab) => <div>Rendered content for tab: {tab.id}</div>}
  </Pane.Content>
</Pane>

Props

| Property | Description | Type | Default | | ---------- | ------------------------------------------------------------------ | --------------------- | ------- | | id | The unique ID corresponding to the layout node. | string | - | | children | Children components rendered inside the pane. | React.ReactNode | - | | style | Optional inline CSS styles applied to the outer pane container. | React.CSSProperties | - | | locked | Optional override to lock this specific pane and disable dragging. | boolean | false |

<Tabs>

A helper component to render and reorder a list of tabs inside a pane.

Usage

import { Tabs } from 'react-zeugma'
;<Tabs
  tabs={['tab1', 'tab2']}
  activeTabId="tab1"
  selectTab={(tabId) => console.log('Select tab:', tabId)}
  removeTab={(tabId) => console.log('Close tab:', tabId)}
  renderTab={({ tabId, activeTabId, onSelect, onRemove }) => (
    <button
      onClick={onSelect}
      className={`px-3 py-1 ${tabId === activeTabId ? 'bg-zinc-800 text-white' : 'text-zinc-400'}`}
    >
      {tabId}
      <span
        className="ml-2 cursor-pointer"
        onClick={(e) => {
          e.stopPropagation()
          onRemove()
        }}
      >
        ×
      </span>
    </button>
  )}
/>

Props

| Property | Description | Type | Default | | -------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | tabs | Array of tab IDs. | string[] | - | | activeTabId | The currently active tab ID. | string | - | | locked | Whether tab dragging/reordering is disabled. | boolean | false | | tabsMetadata | Metadata mapping associated with each tab in the pane. | Record<string, Record<string, unknown>> | - | | selectTab | Callback when a tab is selected. | (id: string) => void | - | | removeTab | Callback when a tab is closed. | (id: string) => void | - | | classNames | Custom class names for the container and tabs. | { container?: string; tab?: string \| ((tabId: string) => string) } | - | | styles | Custom CSS style overrides for the container and tabs. | { container?: CSSProperties; tab?: CSSProperties \| ((tabId: string) => CSSProperties) } | - | | renderTab | Render prop function called for each tab item. | (props: { tabId: string; activeTabId: string; isDragging: boolean; isOver: boolean; metadata?: Record<string, unknown>; onSelect: () => void; onRemove: () => void }) => ReactNode | - |

Hooks

useZeugma(options)

A custom state hook that instantiates the dashboard layout engine and returns the controller.

Usage

import { useZeugma } from 'react-zeugma'

const controller = useZeugma({
  initialLayout: myInitialLayoutTree, // used on mount
  layout: myControlledLayout, // used for controlled mode
  onChange: (nextLayout) => {}, // layout update callback
  locked: false, // lock all dragging and resizing
  fullscreenPaneId: null, // ID of pane to zoom fullscreen
  onFullscreenChange: (paneId) => {}, // callback when pane zoom toggled
})

Options

| Parameter | Description | Type | Default | | -------------------- | --------------------------------------------------------------------------- | --------------------------------------- | ------- | | initialLayout | Initial layout tree structure. Only used on mount. | TreeNode \| null | null | | layout | Controlled layout tree structure. Hook runs in controlled mode if provided. | TreeNode \| null | null | | onChange | Callback triggered when the layout tree updates. | (newLayout: TreeNode \| null) => void | - | | fullscreenPaneId | Controlled fullscreen pane ID. | string \| null | null | | onFullscreenChange | Callback triggered when fullscreen state toggles. | (paneId: string \| null) => void | - | | locked | Global lock status to disable resizing and drag-and-drop operations. | boolean | false |

useZeugmaContext()

Context hook to retrieve layout state, queries, and mutation actions from anywhere under the <Zeugma> tree.

Usage

import { useZeugmaContext } from 'react-zeugma'

const { layout, locked, setLocked, addTab, removePane, selectTab, findPaneById } =
  useZeugmaContext()

Context Values

| Property / Method | Description | Type | | ----------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | layout | The current active layout tree structure. | TreeNode \| null | | fullscreenPaneId | The ID of the maximized fullscreen pane. | string \| null | | locked | Whether the dashboard layout is globally locked. | boolean | | setLayout | React state setter to update the layout tree. | Dispatch<SetStateAction<TreeNode \| null>> | | setFullscreenPaneId | Updates the active fullscreen pane ID. | (paneId: string \| null) => void | | setLocked | Updates the global layout lock state. | Dispatch<SetStateAction<boolean>> | | removePane | Removes a pane and collapses the split. | (paneId: string) => void | | addTab | Adds a tab to a pane, or splits/creates one if target is omitted. | (tabId: string, targetPaneId?: string, metadata?: Record<string, unknown>) => void | | updateMetadata | Mutates a specific tab's metadata. | (id: string, updater: (current: Record<string, unknown> \| undefined) => Record<string, unknown> \| undefined) => void | | updatePaneLock | Toggles the lock status of a specific pane. | (paneId: string, locked: boolean) => void | | selectTab | Focuses/activates a tab within a pane. | (paneId: string, tabId: string) => void | | mergeTab | Programmatically drags and drops a tab from one pane to another. | (draggedTabId: string, targetPaneId: string) => void | | removeTab | Programmatically closes a tab. | (tabId: string) => void | | splitPane | Programmatically splits a pane node and adds a new one. | (targetId: string, direction: SplitDirection, splitType: 'left' \| 'right' \| 'top' \| 'bottom', paneToAdd: string) => void | | updateSplitPercentage | Updates a SplitNode percentage. | (currentNode: SplitNode, percentage: number) => void | | moveTab | Reorders a tab next to another. | (draggedTabId: string, targetTabId: string, position?: 'before' \| 'after') => void | | findPaneById | Queries a PaneNode by its unique ID. | (paneId: string) => PaneNode \| null | | findPaneContainingTab | Queries the parent PaneNode of a tab ID. | (tabId: string) => PaneNode \| null | | findTabById | Queries detailed tab location and state metadata. | (tabId: string) => TabDetails \| null | | getTabMetadata | Gets metadata for a tab ID. | (tabId: string) => Record<string, unknown> \| undefined | | getActiveTabMetadata | Gets metadata for the active tab in a pane. | (paneId: string) => Record<string, unknown> \| undefined |

usePaneContext()

Context hook to access the state and actions of a specific pane. Must be used inside a <Pane> component.

Usage

import { usePaneContext } from 'react-zeugma'

const {
  id,
  tabs,
  activeTabId,
  isDragging,
  isFullscreen,
  toggleFullscreen,
  remove,
  selectTab,
  removeTab,
  updateMetadata,
} = usePaneContext()

Context Values

| Property / Method | Description | Type | | ------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | id | The ID of the current pane. | string | | tabs | List of tab IDs inside the pane. | string[] | | activeTabId | Currently active tab ID. | string | | isDragging | true if this pane is being dragged. | boolean | | isFullscreen | true if this pane is maximized. | boolean | | toggleFullscreen | Toggles maximized state for this pane. | () => void | | remove | Removes this pane from the layout tree. | () => void | | selectTab | Activates a tab within this pane. | (tabId: string) => void | | removeTab | Closes a tab from this pane. | (tabId: string) => void | | metadata | Active tab's custom metadata. | Record<string, unknown> \| undefined | | updateMetadata | Updates active tab's metadata. | (updater: (current: Record<string, unknown> \| undefined) => Record<string, unknown> \| undefined) => void | | locked | Whether the pane or the dashboard is locked. | boolean | | tabsMetadata | Tab metadata mapping for all tabs inside this pane. | Record<string, Record<string, unknown>> \| undefined | | updateTabMetadata | Updates metadata for a specific tab in the pane. | (tabId: string, updater: (current: Record<string, unknown> \| undefined) => Record<string, unknown> \| undefined) => void |

useResizer(props)

Low-level hook for implementing custom pane resizing handles.

Usage

import { useResizer } from 'react-zeugma'

const handlePointerDown = useResizer({
  containerRef,
  isRow,
  direction,
  splitPercentage,
  resizerSize,
  snapThreshold,
  layout,
  currentNode,
  onLayoutChange: (nextTree) => {},
})

Layout Utilities

Import utility functions from react-zeugma/utils to programmatically query or update the serialized layout tree.

Usage

import {
  generateUniqueId,
  splitPane,
  removePane,
  addTab,
  removeTab,
  selectTab,
  mergeTab,
  moveTab,
  findPaneById,
  findPaneContainingTab,
  findTabById,
  computeLayout,
} from 'react-zeugma/utils'

// 1. Generate a random unique pane ID
const newPaneId = generateUniqueId()

// 2. Programmatically split a target pane in the tree
const updatedTree = splitPane(currentTree, 'explorer', 'row', 'right', 'terminal')

// 3. Programmatically add a tab to a pane
const updatedTree = addTab(currentTree, 'editor', 'new-file.js', { status: 'unsaved' })

// 4. Find which pane contains a specific tab
const parentPane = findPaneContainingTab(currentTree, 'new-file.js')

Styling & Class Names

react-zeugma is 100% headless. You must style resizers, previews, and containers by providing custom class names.

Usage

<Zeugma
  controller={controller}
  classNames={{
    dashboard: 'dashboard-root',
    pane: 'pane-wrapper',
    resizer: 'custom-resizer-line',
    dropPreview: 'drop-preview-box',
    tabDropPreview: 'tab-line-preview',
  }}
/>

Class Names Mapping

| Class Key | Description | | ------------------------ | ------------------------------------------------------------------- | | dashboard | Root dashboard grid container. | | dashboardDismissActive | Dashboard container when active item is dragged outside to dismiss. | | dashboardLocked | Dashboard container when layout is globally locked. | | pane | Outer container div of each <Pane>. | | paneLocked | Pane container wrapper when locked. | | paneContainer | Pane inner content container wrapper. | | paneHeader | Drag header wrapper inside the pane. | | paneControls | Controls wrapper container (maximizing, close, lock). | | paneButton | Maximize/Close control buttons. | | dropPreview | Preview indicator box for edge layout splits. | | rootDropPreview | Preview indicator for full layout splits. | | dragOverlay | Absolute portal wrapper following the dragging cursor. | | paneDragPreview | Outer wrapper container of a pane drag preview node. | | tabDragPreview | Outer wrapper container of a tab drag preview node. | | resizer | Pointer-drag splitter handle bars. | | dismissPreview | Background indicator showing visual drag-to-dismiss zones. | | lockedPreview | Hover visual feedback indicator for locked pane zones. | | tabDropPreview | Tab list insertion indicator line. | | tabSeparator | Line separator between static tabs. | | tabContentWrapper | Custom tab content element wrapper. | | tabsContainer | Layout tabs container header bar. | | tab | Individual tab list items. | | tabCloseButton | Close button inside a tab item. | | dragHandle | Drag target region. |