react-resizable-panels

↗ homepage

weekly downloads6.6M

versionv4.6.4

licenseMIT

categoryfrontend

Overview

react-resizable-panels is a React library that provides three core components—PanelGroup, Panel, and PanelResizeHandle—for building resizable split-view layouts. It handles the complex math of percentage-based sizing, constraint enforcement, and drag interactions that would otherwise require significant custom code. With over 6.5 million weekly downloads, it's become a standard solution for interfaces requiring user-adjustable layouts.

The library solves a specific problem: creating fluid, constraint-based resizable panels without manually managing drag events, size calculations, or persistence logic. Unlike CSS-only approaches using flexbox or grid, it provides programmatic control through imperative APIs (resize, collapse, expand) while maintaining declarative React patterns. Layout state automatically persists to localStorage by default, eliminating boilerplate for saving user preferences.

Developers building code editors, admin dashboards, data visualization tools, or any multi-pane interface use this package to avoid reinventing resize logic. It supports both horizontal and vertical orientations, nested groups for complex layouts, and collapsible panels that shrink below minimum sizes when dragged past thresholds. The constraint system uses percentage values (1-100) relative to the parent group, making responsive behavior predictable.

The library's design emphasizes native-feeling interactions—handles respond to drag from any edge, panels animate smoothly during collapse/expand, and constraints prevent invalid layouts. It integrates cleanly with existing React applications without requiring global state management or context providers, keeping component trees simple.

Quick Start

typescript

import { Panel, PanelGroup, PanelResizeHandle } from 'react-resizable-panels';
import { useRef } from 'react';

function CodeEditor() {
  const sidebarRef = useRef(null);

  const toggleSidebar = () => {
    const panel = sidebarRef.current;
    if (panel) {
      panel.isCollapsed() ? panel.expand() : panel.collapse();
    }
  };

  return (
    <div style={{ height: '100vh' }}>
      <button onClick={toggleSidebar}>Toggle Sidebar</button>
      <PanelGroup direction="horizontal" autoSaveId="editor-layout">
        <Panel
          ref={sidebarRef}
          defaultSize={20}
          minSize={10}
          maxSize={40}
          collapsible
          onCollapse={() => console.log('Sidebar collapsed')}
        >
          <div style={{ padding: 16, background: '#f0f0f0', height: '100%' }}>
            <h3>Files</h3>
            <ul>
              <li>index.js</li>
              <li>App.jsx</li>
            </ul>
          </div>
        </Panel>
        
        <PanelResizeHandle style={{ width: 4, background: '#ccc' }} />
        
        <Panel minSize={30}>
          <PanelGroup direction="vertical">
            <Panel defaultSize={70} minSize={20}>
              <div style={{ padding: 16, height: '100%' }}>
                <h3>Editor</h3>
                <textarea style={{ width: '100%', height: '90%' }} />
              </div>
            </Panel>
            
            <PanelResizeHandle style={{ height: 4, background: '#ccc' }} />
            
            <Panel defaultSize={30} minSize={10}>
              <div style={{ padding: 16, background: '#1e1e1e', color: '#fff', height: '100%' }}>
                <h3>Terminal</h3>
                <pre>$ npm start</pre>
              </div>
            </Panel>
          </PanelGroup>
        </Panel>
      </PanelGroup>
    </div>
  );
}

Use Cases

Code Editor Interfaces: Create VS Code-style layouts with a collapsible file explorer sidebar, main editor pane, and terminal panel. Users can resize each section and the layout persists across sessions, matching professional IDE behavior.

Admin Dashboards: Build data-heavy interfaces with a fixed navigation sidebar, resizable table view, and detail panel. Analysts can adjust panel sizes to focus on specific datasets without losing context from other views.

Documentation Sites: Implement side-by-side documentation and live code preview where users drag the divider to see more code or more output. The collapsible feature lets users hide the preview entirely when reading long docs.

Email Clients: Replicate Gmail-style three-pane layouts with collapsible folder list, message list, and reading pane. Users customize their workspace and the autoSaveId prop ensures their preferences load on return visits.

Data Visualization Tools: Create dashboards with resizable chart panels where users can expand specific visualizations for detailed analysis, then collapse them to compare other metrics—all without page navigation or modals.

Pros & Cons

Pros

+Handles complex resize math and constraints automatically—no manual percentage calculations or edge case debugging required
+Built-in localStorage persistence with custom storage API support eliminates boilerplate for saving layout state
+Lightweight bundle size and no external dependencies beyond React—no bloat from utility libraries or animation frameworks
+Imperative APIs (resize, collapse, expand) alongside declarative props provide escape hatches for complex interactions
+Supports nested PanelGroups for building complex grid layouts that pure CSS flex/grid cannot easily achieve

Cons

−Percentage-based sizing (1-100) can be unintuitive when mixing with fixed-size elements like headers or toolbars
−No built-in keyboard navigation for accessibility—requires custom implementation of arrow key resize and focus management
−TypeScript types exist but ref forwarding and imperative API patterns can require verbose type annotations in strict mode
−Custom handle styling requires overriding default classes—no theming system for consistent multi-app design systems
−Vertical layouts with dynamic content heights can cause jumpiness if child content changes size during resize

Install

bash

npm install react-resizable-panels

bash

pnpm add react-resizable-panels

bash

bun add react-resizable-panels

Overview

Quick Start

typescript

import { Panel, PanelGroup, PanelResizeHandle } from 'react-resizable-panels';
import { useRef } from 'react';

function CodeEditor() {
  const sidebarRef = useRef(null);

  const toggleSidebar = () => {
    const panel = sidebarRef.current;
    if (panel) {
      panel.isCollapsed() ? panel.expand() : panel.collapse();
    }
  };

  return (
    <div style={{ height: '100vh' }}>
      <button onClick={toggleSidebar}>Toggle Sidebar</button>
      <PanelGroup direction="horizontal" autoSaveId="editor-layout">
        <Panel
          ref={sidebarRef}
          defaultSize={20}
          minSize={10}
          maxSize={40}
          collapsible
          onCollapse={() => console.log('Sidebar collapsed')}
        >
          <div style={{ padding: 16, background: '#f0f0f0', height: '100%' }}>
            <h3>Files</h3>
            <ul>
              <li>index.js</li>
              <li>App.jsx</li>
            </ul>
          </div>
        </Panel>
        
        <PanelResizeHandle style={{ width: 4, background: '#ccc' }} />
        
        <Panel minSize={30}>
          <PanelGroup direction="vertical">
            <Panel defaultSize={70} minSize={20}>
              <div style={{ padding: 16, height: '100%' }}>
                <h3>Editor</h3>
                <textarea style={{ width: '100%', height: '90%' }} />
              </div>
            </Panel>
            
            <PanelResizeHandle style={{ height: 4, background: '#ccc' }} />
            
            <Panel defaultSize={30} minSize={10}>
              <div style={{ padding: 16, background: '#1e1e1e', color: '#fff', height: '100%' }}>
                <h3>Terminal</h3>
                <pre>$ npm start</pre>
              </div>
            </Panel>
          </PanelGroup>
        </Panel>
      </PanelGroup>
    </div>
  );
}

Use Cases

Pros & Cons

Pros

+Handles complex resize math and constraints automatically—no manual percentage calculations or edge case debugging required
+Built-in localStorage persistence with custom storage API support eliminates boilerplate for saving layout state
+Lightweight bundle size and no external dependencies beyond React—no bloat from utility libraries or animation frameworks
+Imperative APIs (resize, collapse, expand) alongside declarative props provide escape hatches for complex interactions
+Supports nested PanelGroups for building complex grid layouts that pure CSS flex/grid cannot easily achieve

Cons

−Percentage-based sizing (1-100) can be unintuitive when mixing with fixed-size elements like headers or toolbars
−No built-in keyboard navigation for accessibility—requires custom implementation of arrow key resize and focus management
−TypeScript types exist but ref forwarding and imperative API patterns can require verbose type annotations in strict mode
−Custom handle styling requires overriding default classes—no theming system for consistent multi-app design systems
−Vertical layouts with dynamic content heights can cause jumpiness if child content changes size during resize