Panelshow

A modern React library for creating draggable panels with docking and snapping functionality. Perfect for building desktop-like interfaces, dashboard layouts, and complex multi-window applications.

Features

• Floating panels - Create draggable windows that float above your content
• Smart docking - Panels can snap to designated dock areas
• TypeScript support - Fully typed API for better development experience
• Lightweight - Minimal bundle size with zero external dependencies
• Performance focused - Optimized rendering and state management

Installation

npm install panelshow

Quick Start

import React from "react";
import { createPanels, DragArea } from "panelshow";

// Create a panels instance
const panels = createPanels();

// Create a panel
const myPanel = panels.createPanel({
  content: (
    <div>
      <DragArea>
        <h3>Title Bar</h3>
      </DragArea>
      <div>
        <p>Panel content</p>
      </div>
    </div>
  ),
});

function App() {
  return (
    <div>
      {/* Render the panels container */}
      <panels.container />
    </div>
  );
}

export default App;

API Reference

createPanels(config)

Creates a new panels instance with the specified configuration.

Parameters:

• config (optional): Configuration object
  • borderSize (string): Size of panel resize borders (default: '0.5rem')
  • snapClassName (object): CSS classes for snap areas

Returns: Panels

Panels Class

Methods

• createPanel(options) - Create a new panel
• createDockArea(options) - Create a new dock area

Properties

• container - React component that renders all panels

Panel Class

Methods

• open() - Show the panel
• close() - Hide the panel
• dock(area) - Dock panel to a specific area
• undock() - Remove panel from dock area

Properties

• dockArea - Currently docked area (if any)

Hooks

• useDockArea() - React hook to get current dock area

usePanel() Hook

Get the current panel instance within a panel component.

import { usePanel } from "panelshow";

function PanelContent() {
  const panel = usePanel();

  return <button onClick={() => panel.close()}>Close Panel</button>;
}

DragArea Component

A component that makes its content draggable. Should be used within panel content to create drag handles.

import { DragArea } from "panelshow";

<DragArea className="drag-handle">
  <h3>Drag me!</h3>
</DragArea>;

Examples

Basic Panel with Header

const headerPanel = panels.createPanel({
  content: (
    <div className="panel">
      <DragArea className="panel-header">
        <h3>My Panel</h3>
        <button onClick={() => headerPanel.close()}>×</button>
      </DragArea>
      <div className="panel-body">
        <p>Panel content</p>
      </div>
    </div>
  ),
});

Fullscreen snapping

// Create a dock area
const maximiseArea = panels.createDockArea({
  at: {
    width: "100%",
    height: "100%"
  },
  snaps: [{
    y: "0",
    width: "100%"
  }]
});

...

// Maximise the panel
panel.dock(maximiseArea);

Development

# Clone the repository
git clone https://github.com/jamacz/panelshow.git
cd panelshow

# Install dependencies
npm install

# Build the library
npm run build

# Run linting
npm run lint

# Format code
npm run format

License

MIT © jamacz

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Issues

If you find any issues or have feature requests, please open an issue on GitHub.

To-do list

• Forcing panels to stay on the screen on window resize or dragging out of the container
• Order of panels in which they were opened (for a navbar)