React Split Pane

Common errors

• SplitPane does not render or appears collapsed.

  cause The parent container of SplitPane lacks explicit width and height dimensions.
  fix Ensure the parent element of SplitPane has defined CSS properties for `width` and `height`, for example, `<div style={{ width: '100%', height: '100vh' }}><SplitPane>...</SplitPane></div>`.

• Pane sizes reset to default when the component unmounts or the page refreshes.

  cause The application is not persisting the pane sizes between renders or sessions.
  fix Implement the `usePersistence` hook from `react-split-pane/persistence` to save and restore pane sizes to `localStorage` or `sessionStorage`.

• Error: Cannot assign to read only property 'exports' of object '#<Object>'

  cause Attempting to import `react-split-pane` using CommonJS `require()` syntax in an environment expecting ES Modules.
  fix Migrate your import statements from `const { SplitPane } = require('react-split-pane');` to `import { SplitPane } from 'react-split-pane';`.

Warnings

• breaking Version 3.0.0 introduced a complete rewrite of the library, moving to a hooks-based architecture, full TypeScript, and new API patterns. Code written for v2.x or earlier will not be compatible.
  Fix: Review the v3 documentation and examples for `SplitPane` and `Pane` components. Refactor existing split-pane implementations to conform to the new API, especially around event handlers and prop structures.
• gotcha The `SplitPane` component uses `width: 100%` and `height: 100%` by default. Its parent container must have explicit dimensions defined (e.g., `height: 100vh` for vertical splits or a fixed pixel height) for the component to render correctly.
  Fix: Ensure the parent element wrapping `SplitPane` has clearly defined `width` and `height` CSS properties. For full-viewport layouts, `height: 100vh` on the parent is a common solution.
• behavior-change Prior to v3.0.5, controlled panes with fixed pixel sizes would incorrectly scale proportionally when the browser window or container resized. This behavior was fixed to maintain fixed pixel sizes as expected.
  Fix: Upgrade to `react-split-pane@3.0.5` or later. If your application relied on the previous proportional scaling behavior for controlled pixel-sized panes, you will need to adjust your layout logic.
• api-change Version 3.1.0 replaced separate mouse and touch event handlers with the unified Pointer Events API for improved drag UX. The `onResize` and `onResizeStart` callbacks now include `event.pointerType`.
  Fix: When handling resize events, consider using `event.pointerType` ('mouse', 'touch', or 'pen') to differentiate input types within your callback logic. This may simplify existing conditional logic that previously checked for `MouseEvent` vs `TouchEvent`.

Install

• npm install react-split-pane npm
• yarn add react-split-pane yarn
• pnpm add react-split-pane pnpm

Imports

• SplitPane
  wrong:

  const SplitPane = require('react-split-pane');

  correct:

  import { SplitPane } from 'react-split-pane';

  Since v3, the library is hooks-based and primarily designed for ES Modules. CommonJS `require` is not recommended.
• Pane
  wrong:

  import Pane from 'react-split-pane/Pane';

  correct:

  import { Pane } from 'react-split-pane';

  Pane is a named export and used as a child component within SplitPane. Do not attempt to import from a direct file path.
• usePersistence
  wrong:

  import { usePersistence } from 'react-split-pane';

  correct:

  import { usePersistence } from 'react-split-pane/persistence';

  The `usePersistence` hook is located in a sub-path for better tree-shaking and organization.

Quickstart

Demonstrates a basic horizontal split-pane layout with two functional components for a sidebar and main content, setting initial and minimum sizes.

import React from 'react';
import { SplitPane, Pane } from 'react-split-pane';

interface SidebarProps {}
const Sidebar: React.FC<SidebarProps> = () => (
  <div style={{ padding: '20px', background: '#f0f0f0', height: '100%' }}>Sidebar Content</div>
);

interface MainContentProps {}
const MainContent: React.FC<MainContentProps> = () => (
  <div style={{ padding: '20px', background: '#e0e0e0', height: '100%' }}>Main Application Content</div>
);

function App() {
  return (
    <div style={{ width: '100%', height: '100vh', display: 'flex' }}>
      <SplitPane direction="horizontal">
        <Pane minSize="200px" defaultSize="300px">
          <Sidebar />
        </Pane>
        <Pane>
          <MainContent />
        </Pane>
      </SplitPane>
    </div>
  );
}

export default App;