{"id":11756,"library":"react-mosaic-component","title":"React Mosaic Component","description":"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.","status":"active","version":"7.0.0-beta0","language":"javascript","source_language":"en","source_url":"https://github.com/nomcopter/react-mosaic","tags":["javascript","ui","react","component","typescript","tiling-window-manager","window-manager"],"install":[{"cmd":"npm install react-mosaic-component","lang":"bash","label":"npm"},{"cmd":"yarn add react-mosaic-component","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-mosaic-component","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for all React applications. Versions 16 through 19 are supported.","package":"react","optional":false}],"imports":[{"note":"The primary component for creating a mosaic layout is a named export.","wrong":"import Mosaic from 'react-mosaic-component';","symbol":"Mosaic","correct":"import { Mosaic } from 'react-mosaic-component';"},{"note":"Used to wrap individual components within the mosaic layout.","symbol":"MosaicWindow","correct":"import { MosaicWindow } from 'react-mosaic-component';"},{"note":"This is a TypeScript type, so it should be imported using `import type` for clarity and better tree-shaking.","wrong":"import { MosaicNode } from 'react-mosaic-component';","symbol":"MosaicNode","correct":"import type { MosaicNode } from 'react-mosaic-component';"},{"note":"A utility function introduced in v7.x to migrate old binary tree layouts to the new n-ary format.","symbol":"convertLegacyToNary","correct":"import { convertLegacyToNary } from 'react-mosaic-component';"}],"quickstart":{"code":"import React, { useState } from 'react';\nimport { Mosaic, MosaicWindow, getpathFromNode, createBalancedTreeFromElement, MosaicParent, MosaicBranch } from 'react-mosaic-component';\nimport 'react-mosaic-component/src/example/index.css'; // Minimal example styles\n\ntype MyMosaicKey = 'a' | 'b' | 'c' | 'd';\n\nconst ELEMENT_MAP: Record = {\n a:
Panel A Content
,\n b:
Panel B Content
,\n c:
Panel C Content
,\n d:
Panel D Content
,\n};\n\nconst createInitialLayout = () => {\n // In v7.0.0-beta0, the tree structure is n-ary:\n return {\n direction: 'row',\n children: [\n 'a',\n { direction: 'column', children: ['b', 'c'] },\n 'd'\n ]\n } satisfies MosaicParent;\n // For v6.x and earlier, use the binary tree format:\n // return { direction: 'row', first: 'a', second: { direction: 'column', first: 'b', second: 'c' } } as MosaicParent;\n};\n\nexport default function MyMosaicApp() {\n const [currentLayout, setCurrentLayout] = useState>(() => createInitialLayout());\n\n const renderTile = (id: MyMosaicKey, path: MosaicBranch[]) => (\n path={path} createNode={() => 'new'} title={`Window ${id}`}>\n {ELEMENT_MAP[id]}\n \n );\n\n return (\n
\n \n renderTile={renderTile}\n initialValue={currentLayout}\n onChange={setCurrentLayout}\n zeroStateView={
Drag a new window here
}\n />\n
\n );\n}","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"breaking","affected_versions":">=7.0.0-beta0"},{"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.","message":"Type 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.","severity":"breaking","affected_versions":">=7.0.0-beta0"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=6.0.0"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"Older 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.","severity":"gotcha","affected_versions":"<5.2.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Convert your layout definition to the new n-ary format using `{ children: [node, node, ...] }` or use the `convertLegacyToNary()` utility for automatic migration.","cause":"Attempting to use a legacy binary tree layout object with react-mosaic-component v7.0.0-beta0, which expects an n-ary tree structure.","error":"TypeError: Cannot read properties of undefined (reading 'first') or (reading 'second')"},{"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 ``.","cause":"Mismatch between the `react-dnd` version used by your application and the version expected by `react-mosaic-component`, or missing `DndProvider` wrapper.","error":"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."},{"fix":"Update your `MosaicNode` type definitions and layout objects to conform to the n-ary tree structure (`{ direction: 'row' | 'column', children: MosaicNode[] }`) required by v7.x. Alternatively, ensure you are using compatible library versions.","cause":"Trying to use a v6.x (binary) `MosaicNode` type or object literal with v7.x type definitions.","error":"TS2345: Argument of type '{ first: ... }' is not assignable to parameter of type 'MosaicParent'. Property 'children' is missing in type '{ first: ... }'."}],"ecosystem":"npm"}