React Mosaic Component

7.0.0-beta0 · active · verified Sun Apr 19

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.

Common errors

Warnings

Install

Imports

Quickstart

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>
  );
}

view raw JSON →