react-mosaic

react-mosaic is a React tiling window manager. It gives you a drag-to-resize, drag-to-rearrange layout of panels that users can freely rearrange — inspired by IDE window management and i3-style tiling.

📖 Documentation · 🎮 Demo · 📚 API reference · 🚚 Migration from v6

Install

npm install react-mosaic-component react react-dom

Import the stylesheet in your app's entry point:

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

Quick start

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

To render it, mount App from your entry file as usual:

// main.tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { App } from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

The wrapper div needs a real height; Mosaic fills its parent, so a parent with no height gives you an empty page.

That's a two-panel layout with a draggable divider, drag handles on each window title bar, and default toolbar buttons — in 15 lines.

For live editable examples, the n-ary tree model, custom toolbars, tabs, theming, and the full API reference, see the documentation site.

Features

• 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 node type, not a bolted-on convention.
• Controlled or uncontrolled. Pass value + onChange to manage the tree yourself, or initialValue to let the component own it.
• Drag-and-drop. Built on react-dnd with HTML5 and touch backends.
• Theming. Works with or without Blueprint; ships a default CSS theme plus CSS variables you can override.
• Zero-config migration. Legacy v6 binary trees are auto-converted at render time. convertLegacyToNary is available for explicit upgrades.

Using with AI coding agents

The package ships an Agent Skill with the v7 API, the tree model and the common mistakes (like writing the old v6 first/second trees). It works with Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and other agents that support skills:

npx skills add nomcopter/react-mosaic

Or point your agent at node_modules/react-mosaic-component/skills/react-mosaic/SKILL.md, e.g. from your AGENTS.md or CLAUDE.md. For chat assistants, the docs are also available as llms.txt and llms-full.txt.

Browser support

Current versions of Chrome, Edge, Firefox and Safari, on desktop and mobile (touch drag and drop is built in). Internet Explorer is not supported. The package is published as modern JavaScript, so if you target older browsers, let your bundler transpile react-mosaic-component too.

Contributing

Contributions are welcome:

• Clone and install: npm install
• Start the docs site (hot-reloads the demo and live code blocks): npm start
• Build the library: npm run build:lib
• Run tests: npm test
• Lint: npm run lint

Issues and pull requests: github.com/nomcopter/react-mosaic

License

Apache License 2.0 — see LICENSE.

Originally developed by Kevin Verdieck at Palantir Technologies, Inc.