quilt-react

React components and hooks over the shared Quilt engine and DOM renderer. React 18.3 and 19 are supported peers. MIT licensed; ESM, declarations, and sources included.

Quilt is a TypeScript library for split panes, tab groups, and popout windows. It provides a framework-independent layout model, a DOM renderer, and React bindings. Applications supply pane content and manage their own data and storage.

• Nested horizontal and vertical splits, with minimum and maximum pane sizes.
• Tab groups with configurable orientation, appearance, and per-pane permissions.
• CSS theme tokens and typed theme presets.
• Versioned JSON for layout and workspace settings.
• Same-origin popout windows that return their panes when closed.
• Keyboard navigation, optional shortcuts, and optional close confirmation.

Demos

• Vanilla TypeScript
• React
• Customize and export theme JSON from the Theming tab in either demo.
• Electron desktop downloads for macOS, Windows, and Ubuntu/Debian

See screenshots and controls or the application examples. The desktop application contains the same vanilla and React demos and runs offline. Demo builds have no trusted developer certificate; see the installation notes.

Install

npm install quilt-react

quilt-core and quilt-vanilla are installed automatically.

Requires React and React DOM 18.3 or 19. They are peer dependencies so Quilt shares your application’s React instance. In an existing React application, no additional install command is needed. When creating a new application, configure React and React DOM as application dependencies; npm 7 and newer also resolve missing peers automatically unless peer installation is disabled.

TypeScript apps also need matching @types/react and @types/react-dom. Use an ESM-capable bundler with CSS imports. For local archives, see packaging instructions.

Use

Provide <div id="app"></div> in your HTML.

import { createRoot } from 'react-dom/client';
import { Workspace, createLayout, type PaneProps } from 'quilt-react';
import 'quilt-react/styles.css';

type NotesState = { text: string };
const data: NotesState = { text: 'Notes' };
const initialLayout = createLayout({ pane: { id: 'notes', type: 'notes', title: 'Notes' } });
function Notes({ state }: PaneProps<NotesState>) {
  return (
    <textarea
      defaultValue={state.text}
      onChange={(e) => {
        state.text = e.target.value;
      }}
    />
  );
}
const root = createRoot(document.getElementById('app')!);
root.render(
  <Workspace<NotesState>
    initialLayout={initialLayout}
    paneTypes={{ notes: { title: 'Notes', render: Notes } }}
    getPaneState={() => data}
    style={{ height: 600 }}
  />,
);

function disposeWorkspace() {
  root.unmount();
}

Initial configuration is consumed once. Component maps and adapter callbacks can change identity without rebuilding the workspace. Declarative panes inherit application providers through portals. useLayoutSnapshot(workspace) observes layout changes. The model type is LayoutSnapshot; Workspace is the component. WorkspaceHandle, TabRegistry, theme presets, and DOM configuration types are available here too. Attach a WorkspaceHandle ref to call popout from a user gesture; use onReady(handle) for initialization. Before readiness, synchronous operations throw and asynchronous operations reject with Workspace is not ready. React releases its renderer and owned store on unmount.

Only standalone reactRenderer creates separate roots requiring explicit provider wrappers. React-local state does not survive crossing documents: retain data in an application-owned store, and subscribe inside each view when live synchronization is needed. Companion windows are same-origin and depend on the main session.

The stylesheet is identical to quilt-vanilla/styles.css; import either once. See API, lifecycle, and migration.

Documentation

• Getting started
• API reference
• Themes and tab bars
• Registration, React context, persistence, and confirmation
• Three.js integration
• Examples
• Troubleshooting
• Migration
• Changelog