react-mosaic

Layout and Structure

• N-ary tree layouts: A single split can hold any number of children, not just two.
• Tabs as first-class citizens: Tab containers are a native node type in the tree structure.

State Management

• Controlled or uncontrolled: You can manage the layout tree in your own state by passing value and onChange props, or let the component manage it using initialValue.

Interaction and Styling

• Drag-and-drop: Built on react-dnd with support for HTML5 and touch backends.
• Theming: Ships with a default CSS theme and CSS variables for overrides. It works independently or alongside Blueprint.

Compatibility

• Zero-config migration: Automatically converts legacy v6 binary trees to n-ary trees at render time.

Use the uncontrolled pattern when you want Mosaic to manage the layout state internally and you do not need to read or manipulate the tree from outside the component. This is the simplest way to implement a working layout.

Note: Do not provide both initialValue and value simultaneously; doing so will trigger a runtime warning.

<Mosaic
  renderTile={(id, path) => (
    <MosaicWindow path={path} title={`Panel ${id}`}>
      <div style={{ padding: 16 }}>Panel {id}</div>
    </MosaicWindow>
  )}
  initialValue={{
    type: 'split',
    direction: 'row',
    children: ['a', 'b', 'c'],
  }}
/>

To implement a basic tiling layout, use the Mosaic component. You provide an initialValue representing the layout tree and a renderTile function to define how each tile (window) is rendered. Wrap the Mosaic component in a container with a defined height (e.g., 100vh) to ensure the layout fills the space.

import { Mosaic, MosaicWindow } from 'react-mosaic-component';
import 'react-mosaic-component/react-mosaic-component.css';

export function App() {
  return (
    <div style={{ height: '100vh' }}>
      <Mosaic<string>
        renderTile={(id, path) => (
          <MosaicWindow<string> path={path} title={`Panel ${id}`}>
            <div style={{ padding: 20 }}>Contents of {id}</div>
          </MosaicWindow>
        )}
        initialValue={{
          type: 'split',
          direction: 'row',
          children: ['a', 'b'],
        }}
      />
    </div>
  );
}

When changing the schema of your persisted layout, treat the stored tree like any other on-disk format. You can manage changes by:

1. Bumping the storage key: Change STORAGE_KEY (e.g., from v1 to v2) to avoid loading incompatible data.
2. Internal versioning: Include a version field inside the JSON payload and implement a migration function to transform old tree shapes into the current format during the load process.

interface StoredLayout {
  version: 2;
  tree: MosaicNode<string>;
}

function load(): MosaicNode<string> {
  const raw = localStorage.getItem(STORAGE_KEY);
  if (!raw) return DEFAULT_LAYOUT;
  const stored = JSON.parse(raw) as { version: number; tree: unknown };
  if (stored.version === 1) return migrateV1toV2(stored.tree);
  return stored.tree as MosaicNode<string>;
}

To create a custom theme, add a unique class name to the <Mosaic> component and use it to scope your CSS overrides. All library visual rules are namespaced under .mosaic-*.

Example of scoping overrides to a .my-theme class:

.my-theme.mosaic {
  background: #0b1220;
}

.my-theme .mosaic-window {
  background: #111a2c;
  border: 1px solid #1f2a44;
  border-radius: 6px;
}

.my-theme .mosaic-window-title {
  background: linear-gradient(90deg, #1a2236, #111a2c);
  color: #cbd5e0;
}

.my-theme .mosaic-split:hover {
  background: #4c90f0;
}

Then apply it to the component:

<Mosaic className="my-theme" renderTile={/* ... */} />

Every MosaicWindow includes a title bar with default controls. You can replace, add to, or style these controls by passing React nodes to the toolbarControls prop on the MosaicWindow component.

To use the default controls without rebuilding them, import the provided presets from react-mosaic-component:

• DEFAULT_CONTROLS_WITH_CREATION: Includes Split, Expand, and Remove buttons.
• DEFAULT_CONTROLS_WITHOUT_CREATION: Includes Expand and Remove buttons (disables Split).

import {
  DEFAULT_CONTROLS_WITH_CREATION,
  DEFAULT_CONTROLS_WITHOUT_CREATION,
} from 'react-mosaic-component';

// Usage in MosaicWindow
<MosaicWindow
  path={path}
  title="My Panel"
  toolbarControls={DEFAULT_CONTROLS_WITHOUT_CREATION}
/>

In version 7, react-mosaic moved from binary splits (two children) to n-ary splits (any number of children). This allows for shallower trees and easier layout management.

If you are using a legacy binary tree structure in your storage:

1. <Mosaic value={legacyTree}> will automatically convert binary trees to n-ary trees on the fly.
2. You can use the convertLegacyToNary utility for explicit upgrades.

You can select a built-in theme by passing a specific string to the className prop on the <Mosaic> component.

• Default Neutral Theme: Leave className empty.
• Blueprint Light Theme: Use 'mosaic-blueprint-theme'.
• Blueprint Dark Theme: Use 'mosaic-blueprint-theme bp5-dark'. When using this, also set blueprintNamespace="bp5" to ensure internal icons render correctly via the Blueprint icon font.

<Mosaic<string>
  className="mosaic-blueprint-theme bp5-dark"
  blueprintNamespace="bp5"
  renderTile={/* ... */}
  initialValue={/* ... */}
/>

For server-backed persistence, use the onRelease prop to trigger an asynchronous write. It is recommended to use a debounce function (e.g., from lodash-es) to collapse rapid onRelease calls into a single network request, preventing rate-limiting and unnecessary traffic.

import { useMemo } from 'react';
import debounce from 'lodash-es/debounce';

const save = useMemo(
  () =>
    debounce((next: MosaicNode<string>) => {
      fetch('/api/layout', {
        method: 'PUT',
        body: JSON.stringify(next),
      });
    }, 500),
  [],
);

<Mosaic value={tree} onChange={setTree} onRelease={save} renderTile={/*…*/} />

To enable layout rules (split bars, drop targets, drag previews) and the default theme, you must import the library's CSS file in your application.

Without this import, panels will render without dividers, hover states, or drop indicators.

import 'react-mosaic-component/react-mosaic-component.css';