react-mosaic-component

react-mosaic-component is a React tiling window manager that gives applications a drag-to-resize, drag-to-rearrange panel layout inspired by IDE window management and i3-style tiling. Panels are represented as an n-ary tree of split and tab nodes, so a single split can hold any number of children and tabs are a first-class node type rather than a bolted-on convention.

The component can be used controlled (the host app owns the tree via value/onChange) or uncontrolled (it manages state internally from initialValue), and its drag-and-drop is built on react-dnd with HTML5 and touch backends so panels can be rearranged with a mouse or on touch devices. It ships an optional Blueprint-based default theme plus CSS variables for custom styling, and automatically upgrades legacy v6 binary-tree layouts at render time so existing consumers can migrate without a rewrite.

What You Get

• N-ary tree layout model - a MosaicNode tree of split and tabs nodes, so one split can hold any number of children instead of only two
• Controlled or uncontrolled usage - pass value/onChange to own the tree yourself, or initialValue to let the component manage its own state
• Built-in drag-and-drop - panels and tabs are draggable and droppable via react-dnd, with HTML5 and touch backends wired up out of the box
• Tab groups as first-class nodes - MosaicTabsNode holds multiple panel keys plus an active index, with default add/split/remove toolbar buttons and slots to override them
• Blueprint-aware theming - ships a default CSS theme that pairs with Blueprint components, plus CSS variables for applications that don’t use Blueprint
• Legacy tree migration - convertLegacyToNary and automatic at-render conversion let v6 binary-tree consumers upgrade without hand-migrating saved layouts

Common Use Cases

• Building an IDE-style code editor with resizable, rearrangeable file/terminal/output panels
• Adding a customizable multi-pane dashboard where users drag panels into their own layout
• Implementing a data-analysis or BI tool where charts, tables, and filters live in user-arranged tiles
• Powering admin or ops consoles that need tabbed, splittable panels for logs, metrics, and consoles
• Migrating an existing v6 react-mosaic layout to the n-ary tree model without discarding saved user layouts

Under The Hood

Architecture The tree lives as a plain MosaicNode<T> union of split, tabs, or a leaf key (libs/react-mosaic-component/src/lib/types.ts), and Mosaic/MosaicWithoutDragDropContext (Mosaic.tsx) is the only stateful owner of that tree — it decides controlled vs. uncontrolled via an initialValue vs. value check, then delegates every mutation to updateTree/createRemoveUpdate/createHideUpdate/createExpandUpdate in util/mosaicUpdates.ts, which build immutability-helper specs keyed by path so a change at any depth produces a new tree without a full re-derivation. MosaicRoot, MosaicWindow, and the buttons/ components read the tree read-only and call back into a MosaicRootActions context (contextTypes.ts) for remove/expand/hide/show/addTab/removeTab/replaceWith, so the actual drag/tab/toolbar UI is decoupled from tree-mutation logic; swapping the update algorithm would only touch mosaicUpdates.ts and mosaicUtilities.ts, not the rendering components.

Tech Stack A TypeScript (target ES2022, strict: true) React library built inside an Nx monorepo, published from libs/react-mosaic-component via tsup for JS/types and lessc for the CSS theme. Drag-and-drop runs on react-dnd with react-dnd-multi-backend and rdndmb-html5-to-touch to support both HTML5 and touch input through one DndProvider, tree updates go through immutability-helper, small utilities come from lodash-es, and IDs are generated with uuid. Blueprint (@blueprintjs/core/icons) is an optional dev/theming dependency rather than a hard runtime requirement. The docs/demo site is a separate Docusaurus app in the same workspace, built and deployed independently of the published package.

Code Quality Core tree logic carries dedicated Vitest specs — Mosaic.spec.tsx, mosaicUtilities.spec.ts, mosaicUpdates.spec.ts, and boundingBox.spec.ts — exercising the update/utility functions the rest of the UI depends on, run through Nx/Vitest with coverage tooling configured. TypeScript strict mode is enabled workspace-wide, ESLint runs via @nx/eslint-plugin with module-boundary enforcement, commits are linted with commitlint, and Lefthook plus multiple GitHub Actions workflows (PR validation, commit validation, publish) gate changes before merge. Error handling favors explicit console warnings and early returns over silent failures (e.g. addTab/removeTab/show all guard invalid paths and log a specific message rather than throwing or no-oping silently).

API Design The public surface is intentionally small: Mosaic plus MosaicWindow cover the common case in roughly fifteen lines, while renderTabToolbar, renderTabToolbarControls, renderTabTitle, renderTabButton, and canClose let consumers override individual slices of the tab UI without re-implementing the whole toolbar. Types are exported and consistently named around the Mosaic* prefix (MosaicNode, MosaicPath, MosaicUpdate, MosaicRootActions), and the library leans on generics (MosaicKey) so panel identifiers can be strings or numbers without an escape hatch to any. The one piece of friction is the drag-and-drop context: apps that already run their own react-dnd provider need to pass dragAndDropManager explicitly, which is documented but not enforced by the type system.