Registry / web-framework / react-mosaic-component

react-mosaic-component

JSON →
library7.0.0-beta0jsnpmunverified

React Mosaic is a robust tiling window manager for React applications, enabling developers to create complex, customizable split-pane layouts. It provides a declarative API for defining and managing workspace configurations, supporting dynamic resizing, reordering, and adding/removing of individual panes. The package's current stable release series is 6.x (latest 6.1.1), while a significant beta release, 7.0.0-beta0, introduces a new n-ary tree structure and updated type system for React 19 compatibility. React Mosaic differentiates itself by offering deep programmatic control over the layout tree, making it ideal for applications requiring highly flexible and user-definable interfaces, such as IDEs or dashboards. It ships with comprehensive TypeScript types and supports React versions 16 through 19 as a peer dependency.

npm install react-mosaic-component
INSTALL
IMPORT
SIG · REACT-MOSAIC-COMPO
R
react-mosaic-component
web-frameworkjavascriptv7.0.0-beta0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Mosaic
import { Mosaic } from 'react-mosaic-component';
import Mosaic from 'react-mosaic-component';
The primary component for creating a mosaic layout is a named export.
MosaicWindow
import { MosaicWindow } from 'react-mosaic-component';
Used to wrap individual components within the mosaic layout.
MosaicNode
import type { MosaicNode } from 'react-mosaic-component';
import { MosaicNode } from 'react-mosaic-component';
This is a TypeScript type, so it should be imported using `import type` for clarity and better tree-shaking.
convertLegacyToNary
import { convertLegacyToNary } from 'react-mosaic-component';
A utility function introduced in v7.x to migrate old binary tree layouts to the new n-ary format.

Demonstrates a basic multi-panel Mosaic layout with initial state, dynamic rendering of panes, and state management. Includes conditional logic for v6.x vs v7.x layout structures.

import React, { useState } from 'react'; import { Mosaic, MosaicWindow, getpathFromNode, createBalancedTreeFromElement, MosaicParent, MosaicBranch } from 'react-mosaic-component'; import 'react-mosaic-component/src/example/index.css'; // Minimal example styles type MyMosaicKey = 'a' | 'b' | 'c' | 'd'; const ELEMENT_MAP: Record<MyMosaicKey, JSX.Element> = { a: <div>Panel A Content</div>, b: <div>Panel B Content</div>, c: <div>Panel C Content</div>, d: <div>Panel D Content</div>, }; const createInitialLayout = () => { // In v7.0.0-beta0, the tree structure is n-ary: return { direction: 'row', children: [ 'a', { direction: 'column', children: ['b', 'c'] }, 'd' ] } satisfies MosaicParent<MyMosaicKey>; // For v6.x and earlier, use the binary tree format: // return { direction: 'row', first: 'a', second: { direction: 'column', first: 'b', second: 'c' } } as MosaicParent<MyMosaicKey>; }; export default function MyMosaicApp() { const [currentLayout, setCurrentLayout] = useState<MosaicNode<MyMosaicKey>>(() => createInitialLayout()); const renderTile = (id: MyMosaicKey, path: MosaicBranch[]) => ( <MosaicWindow<MyMosaicKey> path={path} createNode={() => 'new'} title={`Window ${id}`}> {ELEMENT_MAP[id]} </MosaicWindow> ); return ( <div style={{ width: '100vw', height: '100vh', display: 'flex' }}> <Mosaic<MyMosaicKey> renderTile={renderTile} initialValue={currentLayout} onChange={setCurrentLayout} zeroStateView={<div>Drag a new window here</div>} /> </div> ); }
Debug
Known issues
breakingThe internal tree structure for defining layouts changed from a binary tree (`{ first: node, second: node }`) to an n-ary tree (`{ children: [node, node, ...] }`) in v7.0.0-beta0. Existing layouts defined with the old format will not render correctly.
fix
Use the `convertLegacyToNary()` utility function to automatically migrate existing binary tree layouts to the new n-ary format. Update any manually constructed layout objects to conform to the new `{ children: [...] }` structure.
affects: >=7.0.0-beta0
breakingType definitions for JSX elements were updated in v7.0.0-beta0 to support React 19. Projects using older React versions with v7 types may encounter compatibility issues.
fix
Ensure your project is using React 19 (or compatible versions) when upgrading to react-mosaic-component v7.x. Downgrade to a v6.x release if React 19 compatibility is not feasible.
affects: >=7.0.0-beta0
breakingVersion 6.0.0 upgraded `react-dnd` to `^16`. Incompatible versions of `react-dnd` as a direct or transitive dependency can lead to runtime errors or broken drag-and-drop functionality.
fix
Ensure `react-dnd` is resolved to a compatible version (e.g., `^16` for react-mosaic-component v6.x, `^14` for v5.x). Check your `yarn.lock` or `package-lock.json` and use overrides or resolutions if necessary to enforce the correct `react-dnd` version.
affects: >=6.0.0
breakingVersion 5.0.0 removed all direct Blueprint UI library dependencies, making it optionally cross-platform. This change alters the rendered DOM structure and may break existing CSS styles or Blueprint-specific integrations.
fix
Review and update any custom CSS selectors or styling rules that relied on Blueprint-specific class names or DOM hierarchies within `react-mosaic-component`. Adjust any Blueprint-related imports or configurations that assumed direct integration.
affects: >=5.0.0
gotchaOlder versions of npm (pre-7) might not automatically install peer dependencies, leading to runtime errors if `react` (and `react-dnd` indirectly) are not explicitly installed.
fix
Ensure `react` and `react-dom` are installed as direct dependencies in your project. If issues persist, manually install `react-dnd` with a compatible version if it's not automatically handled by the package manager.
affects: <5.2.2
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'first') or (reading 'second')
Attempting to use a legacy binary tree layout object with react-mosaic-component v7.0.0-beta0, which expects an n-ary tree structure.
fix
Convert your layout definition to the new n-ary format using `{ children: [node, node, ...] }` or use the `convertLegacyToNary()` utility for automatic migration.
Error: Could not find the drag and drop manager. Either make sure you've wrapped your top-level component with 'DndProvider', or make sure your 'dragAndDropManager' is a valid instance.
Mismatch between the `react-dnd` version used by your application and the version expected by `react-mosaic-component`, or missing `DndProvider` wrapper.
fix
Ensure `react-dnd` is installed and resolved to a compatible version (e.g., `^16` for `react-mosaic-component` v6.x). Wrap your root component, or at least the `Mosaic` component, with `<DndProvider manager={HTML5Backend}>`.
TS2345: Argument of type '{ first: ... }' is not assignable to parameter of type 'MosaicParent<T>'. Property 'children' is missing in type '{ first: ... }'.
Trying to use a v6.x (binary) `MosaicNode` type or object literal with v7.x type definitions.
fix
Update your `MosaicNode` type definitions and layout objects to conform to the n-ary tree structure (`{ direction: 'row' | 'column', children: MosaicNode<T>[] }`) required by v7.x. Alternatively, ensure you are using compatible library versions.
Upgrade
Version history
7.0.0-beta0latest on npm
Audit
Dependencies
reactrequiredPeer dependency required for all React applications. Versions 16 through 19 are supported.
Agent activity
4 hits · last 30 days
node
4
Resources
react-mosaic-component — npm install react-mosaic-component · libregistry