BatStack Draggable Grid

A powerful and flexible draggable grid component for React applications. This package provides a customizable grid system that allows for dynamic, responsive layouts with draggable elements.

Features

• 🎯 Draggable grid elements with smooth animations
• 📱 Responsive design with breakpoint support
• 🎨 Customizable styling and layout
• 🔄 Automatic gravity and collision detection
• 🖱️ Intuitive mouse interaction
• 📦 Built with TypeScript for type safety
• ⚡️ Powered by Zustand for state management

Installation

# Using npm
npm install batstack-draggable-grid

# Using yarn
yarn add batstack-draggable-grid

# Using pnpm
pnpm add batstack-draggable-grid

Usage

import { Grid } from 'batstack-draggable-grid';

const MyComponent = () => {
  const elements = [
    {
      id: '1',
      gridRect: {
        // XXL breakpoint (≥1400px)
        xxl: {
          position: { col: 1, row: 1 },
          size: { colSpan: 2, rowSpan: 2 }
        },
        // XL breakpoint (≥1200px)
        xl: {
          position: { col: 1, row: 1 },
          size: { colSpan: 2, rowSpan: 2 }
        },
        // LG breakpoint (≥992px)
        lg: {
          position: { col: 1, row: 1 },
          size: { colSpan: 2, rowSpan: 2 }
        },
        // MD breakpoint (≥768px)
        md: {
          position: { col: 1, row: 1 },
          size: { colSpan: 1, rowSpan: 2 }
        },
        // SM breakpoint (≥576px)
        sm: {
          position: { col: 1, row: 1 },
          size: { colSpan: 1, rowSpan: 1 }
        }
      },
      children: <div>Your content here</div>
    }
  ];

  return (
    <div style={{ width: '100%', height: '100vh' }}>
      <Grid elements={elements} />
    </div>
  );
};

Element Configuration

Each element in the grid must be configured with the following properties:

Required Properties

• id: string - Unique identifier for the element
• gridRect: object - Responsive layout configuration for different breakpoints
  • xxl: GridRect - Layout for XXL screens (≥1400px)
  • xl: GridRect - Layout for XL screens (≥1200px)
  • lg: GridRect - Layout for LG screens (≥992px)
  • md: GridRect - Layout for MD screens (≥768px)
  • sm: GridRect - Layout for SM screens (≥576px)

GridRect Structure

Each breakpoint configuration (GridRect) requires:

{
  position: {
    col: number;  // Column position (1-based)
    row: number;  // Row position (1-based)
  },
  size: {
    colSpan: number;  // Number of columns to span
    rowSpan: number;  // Number of rows to span
  }
}

Optional Properties

• children: React.ReactNode - Content to be rendered inside the grid element

Development

To run the development environment:

# Install dependencies
yarn install

# Start development server
yarn dev

This will start both the package watcher and the example application.

Building

To build the package:

yarn build

License

Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) © Beniamin Batkowski

This license allows you to:

• Use the software for free
• Modify the software
• Create derivative works
• Share the software (with attribution)

But restricts you from:

• Using it commercially without permission

Dependencies

This package uses the following major dependencies:

• Zustand - MIT License
• React - MIT License