@aiquants/resize-panels

Resizable panel layout components for React. Packages the layout management, DOM measurement, and snapping logic previously used in application templates into a reusable library.

Key Features

• Core Components: PanelGroup, Panel, and PanelResizeHandle synchronized via a central state reducer for layout and DOM measurements.
• Snap & Noise Filtering: Uses calculateSnapThreshold and noise filtering to prevent layout jitter and unwanted collapse during resizing.
• Directional Collapsible Control: Declarative collapsible settings (from: 'start' | 'end' | 'both') and usePanelControls hook support collapsing/expanding via both drag actions and UI controls.
• Keyboard & Touch Accessibility: Handles support mouse/touch dragging as well as keyboard navigation via arrow keys (5x step multiplier with Shift). Drag states remain robust under multi-touch or pointercancel interruptions.
• Full RTL Layout Support: Under dir="rtl", drag interactions, keyboard shortcuts, and handle positions automatically mirror visual layout directions.
• Auto-Persistence: Set autoSaveId to save panel sizes to localStorage (debounced after layout stabilization) and restore state on page reloads.
• Debug & Visualization: Enable showDebugInfo to inspect panel metrics and constraint violations via PanelDebugInfo and a global debug overlay (dynamically lazy-loaded, zero overhead in production bundles).

Installation

Monorepo workspace dependency:

// consumer package.json
{
  "dependencies": {
    "@aiquants/resize-panels": "workspace:*"
  }
}

Standard package manager installation:

pnpm add @aiquants/resize-panels

Quick Start

import { useId } from "react"
import { PanelGroup, Panel, PanelResizeHandle } from "@aiquants/resize-panels"

export const Example = () => {
    const baseId = useId()

    return (
        <PanelGroup id={`${baseId}-group`} direction="horizontal" className="h-96">
            <Panel id={`${baseId}-left`} defaultSize={{ value: 200, unit: "pixels" }} className="bg-slate-100">
                Left Panel
            </Panel>
            <PanelResizeHandle id={`${baseId}-handle`} />
            <Panel id={`${baseId}-right`} defaultSize={{ value: 60, unit: "percentage" }} className="bg-slate-50">
                Right Panel
            </Panel>
        </PanelGroup>
    )
}

Enabling Collapsible Panels

Specify collapsible={{ from: "start" }} or collapsible={{ from: "end" }} on a Panel to enable automatic collapse/expand when dragging the corresponding handle to container boundaries. Set defaultCollapsed to set initial state to collapsed. Use collapsible={{ from: "both" }} to allow collapsing from either edge.

<PanelGroup direction="horizontal" className="h-96">
    <Panel id="sidebar" defaultSize={{ value: 240, unit: "pixels" }} collapsible={{ from: "end" }}>
        Sidebar
    </Panel>
    <PanelResizeHandle id="handle" />
    <Panel id="main" defaultSize={{ value: 60, unit: "percentage" }}>
        Main Content
    </Panel>
</PanelGroup>

Programmatic Controls via Hook

Use usePanelControls(panelId) inside any child component of PanelGroup to trigger collapse, expand, or toggle actions:

import { PanelGroup, Panel, PanelResizeHandle, usePanelControls } from "@aiquants/resize-panels"

const PanelToggleButtons = ({ panelId, label }: { panelId: string; label: string }) => {
    const { panel, isCollapsed, collapse, expand, toggle, canCollapseFromStart, canCollapseFromEnd } = usePanelControls(panelId)
    const direction = panel?.collapsedByDirection ?? (canCollapseFromStart ? "start" : "end")

    return (
        <div className="flex items-center gap-2">
            <span>{label}</span>
            <button onClick={() => collapse(direction)} disabled={(!canCollapseFromStart && !canCollapseFromEnd) || isCollapsed}>
                Collapse
            </button>
            <button onClick={() => expand(direction)} disabled={!isCollapsed || (!canCollapseFromStart && !canCollapseFromEnd)}>
                Expand
            </button>
            <button onClick={() => toggle(direction)} disabled={!canCollapseFromStart && !canCollapseFromEnd}>
                {isCollapsed ? "Switch to Expand" : "Switch to Collapse"}
            </button>
        </div>
    )
}

export const Example = () => (
    <PanelGroup direction="horizontal" className="h-96">
        <Panel id="sidebar" defaultSize={{ value: 240, unit: "pixels" }} collapsible={{ from: "end" }}>
            <PanelToggleButtons panelId="sidebar" label="Sidebar" />
        </Panel>
        <PanelResizeHandle id="split" />
        <Panel id="main" defaultSize={{ value: 60, unit: "percentage" }}>
            <PanelToggleButtons panelId="details" label="Details Panel" />
        </Panel>
        <PanelResizeHandle id="split-right" />
        <Panel id="details" defaultSize={{ value: 40, unit: "percentage" }} collapsible={{ from: "start" }}>
            Details
        </Panel>
    </PanelGroup>
)

Component API

PanelGroup Properties

| Property | Type | Description | | --- | --- | --- | | id | string | Group identifier (reflected in data-panel-group-id). Recommended when mounting multiple groups | | direction | 'horizontal' \| 'vertical' | Panel layout orientation | | className / style | string / React.CSSProperties | Additional styling for the container | | children | React.ReactNode | Panel and PanelResizeHandle child elements | | showDebugInfo | boolean | Enables PanelDebugInfo and global debug overlay | | onLayout | (sizes: number[]) => void | Callback emitting updated pixel size arrays on resize/init | | autoSaveId | string | Key used to automatically persist and restore panel sizes in localStorage |

Panel Properties

| Property | Type | Description | | --- | --- | --- | | id | string | Panel identifier. Explicit string required for SSR consistency | | defaultSize | { value: number; unit: 'pixels' \| 'percentage' } \| number | Initial panel size (numbers parsed as percentages) | | minSize / maxSize | FlexibleSize | Panel size boundaries (pixels or percentages) | | collapsible | { from: 'start' \| 'end' \| 'both' } | Declarative collapsible edge configuration | | defaultCollapsed | boolean | Whether the panel starts collapsed | | pixelAdjustPriority | number | Priority for assigning excess space to pixel-based panels | | className / style | string / React.CSSProperties | Panel container styles |

PanelResizeHandle Properties

| Property | Type | Description | | --- | --- | --- | | id | string | Handle identifier (reflected in data-resize-handle-id) | | disabled | boolean | Disables mouse dragging and keyboard resizing when true | | thickness | number | Primary axis thickness of the handle's interactive area in pixels (8px default) | | indicator | boolean \| PanelResizeHandleIndicatorConfig | Toggle indicator visibility or provide custom pill/bar dimensions and CSS classes | | indicatorThickness | number | Shorthand for indicator pill wrapper thickness in pixels (6px default) | | indicatorLength | number | Shorthand for indicator pill wrapper length in pixels (48px horizontal / 80px vertical default) | | indicatorBarThickness | number | Shorthand for indicator inner bar thickness in pixels (2px default) | | indicatorBarLength | number | Shorthand for indicator inner bar length in pixels (32px horizontal / 64px vertical default) | | title | string | Custom tooltip text for the handle element | | onDragging | (isDragging: boolean) => void | Callback triggered on drag start and end (including pointercancel) | | className / style | string / React.CSSProperties | Additional styling for the resize handle | | children | React.ReactNode | Custom indicator element rendered inside handle (overrides default indicator) |

Handles render as <button> elements accessible via arrow keys (←/→ for horizontal, ↑/↓ for vertical). Holding Shift increases step distance 5x. Under dir="rtl", keyboard and drag directions adjust to visual layout. Dimension options snap to integer pixels via roundHalfToEven to eliminate subpixel blurring.

Hooks & Utilities

• useResizablePanels: Internal hook used by PanelGroup. Useful for building custom panel containers.
• usePanelGroup: Context accessor for panel lists and layout state.
• usePanelControls: Provides collapse, expand, and toggle operations for a specified panel ID.
• saveLayout & loadLayout: Programmatically persist or restore layout state.
• getPanelElement, getPanelGroupElement, getResizeHandleElement: DOM element query helpers via data-* attributes.

Layout Persistence

When autoSaveId is provided to PanelGroup, panel dimensions are saved to localStorage (debounced by 200ms after ResizeObserver stabilization). Re-opening the page automatically applies loadLayout(autoSaveId) to restore both pixel- and percentage-based panels.

Debugging & Inspection

Enabling showDebugInfo on PanelGroup renders overlay inspection metrics over each Panel (showing collapse status, measured dimensions, and percentages) along with a global container inspector listing handle thickness (8px default) and constraint alerts. Debug components are lazily imported (React.lazy) and excluded from production builds when unused.

Styling (CSS)

The package provides two CSS consumption options:

• Tailwind v4 Host: Import components-only styles into layer(components) and configure Tailwind to scan package source files:

  /* app tailwind.css */
  @import "@aiquants/resize-panels/styles/resize-panels.css" layer(components);
  @source "../node_modules/@aiquants/resize-panels/src/**/*.{ts,tsx}";
  /* monorepo: @source "../../../../packages/resize-panels/src/**/*.{ts,tsx}"; */

• Non-Tailwind Host: Import the self-contained standalone CSS bundle:

  @import "@aiquants/resize-panels/styles/resize-panels.standalone.css";

  Dark mode activates based on the .dark class on <html>.

Demo App

Run the included workspace demo app:

pnpm --filter '@aiquants/resize-panels-demo' dev

Open http://localhost:5175 to test interactive layouts.

Build

pnpm --filter '@aiquants/resize-panels' build

Outputs built artifacts to dist/.