allotment

Allotment is a React component for building resizable split-pane layouts — the kind of horizontal or vertical panel arrangement seen in code editors, dashboards, and IDE-style tools. Its resizing engine (sashes, layout priorities, and proportional sizing) is derived directly from the same split-view codebase that powers VS Code’s own editor panels, so it reproduces that exact drag, snap, and minimum/maximum-size behavior in any React application.

Panes are declared declaratively as children of an <Allotment> component, with an optional <Allotment.Pane> wrapper for per-pane control over minimum/maximum size, preferred size, snapping, and visibility. The library handles adding, removing, and reordering panes at runtime, imperative reset/resize via a ref handle, and styling through CSS custom properties and class hooks, while staying unopinionated about what actually renders inside each pane.

What You Get

• An <Allotment> container component that arranges children into horizontal or vertical resizable panes
• An <Allotment.Pane> component for per-pane minSize, maxSize, preferredSize, priority, and visibility control
• Draggable sash dividers with hover/active states, double-click-to-reset, and snap-to-zero collapsing
• An imperative ref handle (reset, resize) for programmatic control of pane sizes
• onChange/onDragStart/onDragEnd/onReset/onVisibleChange callbacks for tracking layout state
• CSS custom properties (--focus-border, --separator-border) and a documented class API for styling

Common Use Cases

• Building code editor or IDE-style UIs with resizable sidebar, editor, and terminal panes
• Dashboards where users drag to resize adjacent chart, table, or detail panels
• Admin tools with a collapsible/resizable navigation or inspector panel alongside main content
• Documentation or playground sites that split an editable input pane from a live preview pane

Under The Hood

Architecture The library is layered: Allotment (src/allotment.tsx) is the public React component that owns props, refs, and DOM children, and delegates all actual layout math to a framework-agnostic SplitView (src/split-view/split-view.ts), which composes a Sash (src/sash/sash.ts) for drag interactions, a PaneView (src/pane-view/pane-view.ts) as the resizable-view abstraction, and a small LayoutService for propagating container size. React effects (useIsomorphicLayoutEffect) construct the SplitView once on mount and thereafter diff children on every render — computing enter/update/exit/reorder sets against a previousKeys ref — to imperatively call addView/removeView/moveView on the underlying SplitView rather than re-rendering it, which is the core coupling point: if that reconciliation loop or the SplitView event contract changes, the whole pane lifecycle (mount, resize, reorder, remove) breaks.

Tech Stack Written in TypeScript targeting ES2020, built as a React 18/19-compatible component with peer dependencies on react/react-dom (^17 || ^18 || ^19). Runtime dependencies are deliberately small and framework-independent: eventemitter3 for the SplitView’s internal event bus, classnames for conditional class composition, fast-deep-equal and lodash.clamp/lodash.debounce for comparisons and numeric bounds, and usehooks-ts for the resize-observer hook. The package is built with Rollup into both a legacy CommonJS bundle and a modern ESM bundle plus a separate tsc pass for declaration files, and its component gallery/docs are built with Storybook and a static docs site under website/.

Code Quality Testing is comprehensive for the core layout engine but exists at only one layer: split-view.test.ts unit-tests the framework-agnostic SplitView extensively (add/remove/resize/proportional-layout/priority scenarios) via Jest and jsdom, but there is no test coverage for the Allotment React component itself, so the React-to-SplitView reconciliation logic in allotment.tsx is only exercised indirectly through Storybook stories and manual use. The codebase is fully typed under strict TypeScript, uses ESLint with import-sorting and React-hooks rules, Prettier formatting enforced via Husky/lint-staged pre-commit hooks, and a GitHub Actions CI workflow that runs the build and test suite.

What Makes It Unique Allotment’s differentiator is fidelity to VS Code’s actual panel-resizing behavior rather than a generic splitter reimplementation — its SplitView, Sash, and layout-priority model are a direct, framework-agnostic port of VS Code’s own split-view internals, giving it VS Code’s exact minimum/maximum-size clamping, proportional-vs-priority resize distribution, and snap-to-zero collapsing semantics. That framework-agnostic core is then wrapped in a thin, purely declarative React layer, keeping the actual resizing math independent of React’s render cycle.