React-Grid-Layout

import ReactGridLayout, { useContainerWidth, verticalCompactor } from 'react-grid-layout';

function MyGrid() {
  const { width, containerRef, mounted } = useContainerWidth();

  return (
    <div ref={containerRef}>
      {mounted && (
        <ReactGridLayout
          width={width}
          layout={layout}
          gridConfig={{ cols: 12, rowHeight: 30 }}
          dragConfig={{ enabled: true, handle: '.handle' }}
          compactor={verticalCompactor}
        >
          {children}
        </ReactGridLayout>
      )}
    </div>
  );
}

interface UseContainerWidthOptions {
  /** Delay render until width is measured. Useful for SSR. Default: false */
  measureBeforeMount?: boolean;
  /** Initial width before measurement. Default: 1280 */
  initialWidth?: number;
}

interface UseContainerWidthResult {
  /** Current container width in pixels */
  width: number;
  /** Whether the container has been measured at least once */
  mounted: boolean;
  /** Ref to attach to the container element */
  containerRef: RefObject<HTMLDivElement | null>;
  /** Manually trigger a width measurement */
  measureWidth: () => void;
}

interface UseGridLayoutOptions {
  /** Initial layout */
  layout: Layout;
  /** Number of columns */
  cols: number;
  /** Block movement into occupied space instead of pushing items */
  preventCollision?: boolean;
  /** Called when layout changes */
  onLayoutChange?: (layout: Layout) => void;
  /** Compactor for layout compaction (default: verticalCompactor) */
  compactor?: Compactor;
}

interface UseGridLayoutResult {
  /** Current layout */
  layout: Layout;
  /** Set layout directly */
  setLayout: (layout: Layout) => void;
  /** Current drag state (activeDrag, oldDragItem, oldLayout) */
  dragState: DragState;
  /** Current resize state (resizing, oldResizeItem, oldLayout) */
  resizeState: ResizeState;
  /** Current drop state (droppingDOMNode, droppingPosition) */
  dropState: DropState;
  /** Start dragging an item */
  onDragStart: (itemId: string, x: number, y: number) => LayoutItem | null;
  /** Update drag position */
  onDrag: (itemId: string, x: number, y: number) => void;
  /** Stop dragging */
  onDragStop: (itemId: string, x: number, y: number) => void;
  /** Start resizing an item */
  onResizeStart: (itemId: string) => LayoutItem | null;
  /** Update resize dimensions */
  onResize: (
    itemId: string,
    w: number,
    h: number,
    x?: number,
    y?: number
  ) => void;
  /** Stop resizing */
  onResizeStop: (itemId: string, w: number, h: number) => void;
  /** Handle external drag over */
  onDropDragOver: (
    droppingItem: LayoutItem,
    position: DroppingPosition
  ) => void;
  /** Handle external drag leave */
  onDropDragLeave: () => void;
  /** Complete external drop */
  onDrop: (droppingItem: LayoutItem) => void;
  /** Container height in grid rows */
  containerHeight: number;
  /** Whether any drag/resize/drop is active */
  isInteracting: boolean;
  /** The compactor being used */
  compactor: Compactor;
}

interface UseResponsiveLayoutOptions<B extends string = DefaultBreakpoints> {
  /** Current container width */
  width: number;
  /** Breakpoint definitions (name → min-width). Default: {lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0} */
  breakpoints?: Record<B, number>;
  /** Column counts per breakpoint. Default: {lg: 12, md: 10, sm: 6, xs: 4, xxs: 2} */
  cols?: Record<B, number>;
  /** Layouts for each breakpoint */
  layouts?: Partial<Record<B, Layout>>;
  /** Compactor for layout compaction (default: verticalCompactor) */
  compactor?: Compactor;
  /** Called when breakpoint changes */
  onBreakpointChange?: (newBreakpoint: B, cols: number) => void;
  /** Called when layout changes */
  onLayoutChange?: (layout: Layout, layouts: Record<B, Layout>) => void;
  /** Called when width changes */
  onWidthChange?: (
    width: number,
    margin: [number, number],
    cols: number,
    padding: [number, number] | null
  ) => void;
}

interface UseResponsiveLayoutResult<B extends string = DefaultBreakpoints> {
  /** Current layout for the active breakpoint */
  layout: Layout;
  /** All layouts by breakpoint */
  layouts: Partial<Record<B, Layout>>;
  /** Current active breakpoint */
  breakpoint: B;
  /** Column count for the current breakpoint */
  cols: number;
  /** Update layout for a specific breakpoint */
  setLayoutForBreakpoint: (breakpoint: B, layout: Layout) => void;
  /** Update all layouts */
  setLayouts: (layouts: Partial<Record<B, Layout>>) => void;
  /** Sorted array of breakpoint names (smallest to largest) */
  sortedBreakpoints: B[];
}

type DefaultBreakpoints = "lg" | "md" | "sm" | "xs" | "xxs";

interface ReactGridLayoutProps {
  // Required
  children: React.ReactNode;
  width: number; // Container width in pixels

  // Configuration interfaces (see below for details)
  gridConfig?: Partial<GridConfig>; // Grid measurement settings
  dragConfig?: Partial<DragConfig>; // Drag behavior settings
  resizeConfig?: Partial<ResizeConfig>; // Resize behavior settings
  dropConfig?: Partial<DropConfig>; // External drop settings
  positionStrategy?: PositionStrategy; // CSS positioning strategy
  compactor?: Compactor; // Layout compaction strategy

  // Layout data
  layout?: Layout; // Layout definition
  droppingItem?: LayoutItem; // Item configuration when dropping from outside

  // Container
  autoSize?: boolean; // Auto-size container height (default: true)
  className?: string;
  style?: React.CSSProperties;
  innerRef?: React.Ref<HTMLDivElement>;

  // Callbacks
  onLayoutChange?: (layout: Layout) => void;
  onDragStart?: EventCallback;
  onDrag?: EventCallback;
  onDragStop?: EventCallback;
  onResizeStart?: EventCallback;
  onResize?: EventCallback;
  onResizeStop?: EventCallback;
  onDrop?: (layout: Layout, item: LayoutItem | undefined, e: Event) => void;
  onDropDragOver?: (e: DragEvent) => { w?: number; h?: number } | false | void;
}

interface GridConfig {
  cols: number; // Number of columns (default: 12)
  rowHeight: number; // Row height in pixels (default: 150)
  margin: [number, number]; // [x, y] margin between items (default: [10, 10])
  containerPadding: [number, number] | null; // Container padding (default: null, uses margin)
  maxRows: number; // Maximum rows (default: Infinity)
}

interface DragConfig {
  enabled: boolean; // Enable dragging (default: true)
  bounded: boolean; // Keep items within container (default: false)
  handle?: string; // CSS selector for drag handle
  cancel?: string; // CSS selector to cancel dragging
  threshold: number; // Pixels to move before drag starts (default: 3)
}

interface ResizeConfig {
  enabled: boolean; // Enable resizing (default: true)
  handles: ResizeHandleAxis[]; // Handle positions (default: ['se'])
  handleComponent?: React.ReactNode | ((axis, ref) => React.ReactNode);
}

interface DropConfig {
  enabled: boolean; // Allow external drops (default: false)
  defaultItem: { w: number; h: number }; // Default size (default: { w: 1, h: 1 })
  onDragOver?: (e: DragEvent) => { w?: number; h?: number } | false | void;
}

import {
  transformStrategy, // Default: use CSS transforms
  absoluteStrategy, // Use top/left positioning
  createScaledStrategy // For scaled containers
} from "react-grid-layout/core";

// Example: scaled container
<div style={{ transform: 'scale(0.5)' }}>
  <ReactGridLayout positionStrategy={createScaledStrategy(0.5)} ... />
</div>

import {
  verticalCompactor, // Default: compact items upward
  horizontalCompactor, // Compact items leftward
  noCompactor, // No compaction (free positioning)
  getCompactor // Factory: getCompactor('vertical', allowOverlap, preventCollision)
} from "react-grid-layout/core";

interface ResponsiveGridLayoutProps<B extends string = string> {
  // Responsive configuration
  breakpoint?: B; // Current breakpoint (auto-detected)
  breakpoints?: Record<B, number>; // Breakpoint definitions (default: {lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0})
  cols?: Record<B, number>; // Columns per breakpoint (default: {lg: 12, md: 10, sm: 6, xs: 4, xxs: 2})
  layouts?: Record<B, Layout>; // Layouts per breakpoint

  // Can be fixed or per-breakpoint
  margin?: [number, number] | Partial<Record<B, [number, number]>>;
  containerPadding?:
    | [number, number]
    | Partial<Record<B, [number, number] | null>>
    | null;

  // Callbacks
  onBreakpointChange?: (newBreakpoint: B, cols: number) => void;
  onLayoutChange?: (layout: Layout, layouts: Record<B, Layout>) => void;
  onWidthChange?: (
    width: number,
    margin: [number, number],
    cols: number,
    padding: [number, number] | null
  ) => void;
}

interface LayoutItem {
  i: string; // Unique identifier (must match child key)
  x: number; // X position in grid units
  y: number; // Y position in grid units
  w: number; // Width in grid units
  h: number; // Height in grid units
  minW?: number; // Minimum width (default: 0)
  maxW?: number; // Maximum width (default: Infinity)
  minH?: number; // Minimum height (default: 0)
  maxH?: number; // Maximum height (default: Infinity)
  static?: boolean; // If true, not draggable or resizable
  isDraggable?: boolean; // Override grid isDraggable
  isResizable?: boolean; // Override grid isResizable
  isBounded?: boolean; // Override grid isBounded
  resizeHandles?: Array<"s" | "w" | "e" | "n" | "sw" | "nw" | "se" | "ne">;
}

import {
  verticalCompactor,
  horizontalCompactor,
  noCompactor,
  getCompactor,
  moveElement,
  collides,
  getFirstCollision,
  validateLayout
  // ... and more
} from "react-grid-layout/core";

interface Compactor {
  /** Identifies the compaction type */
  type: "vertical" | "horizontal" | null | string;

  /**
   * Whether items can overlap each other.
   *
   * When true:
   * - Items can be placed on top of other items
   * - Dragging into another item does NOT push it away
   * - Compaction is skipped after drag/resize
   *
   * Use for: layered dashboards, free-form layouts
   */
  allowOverlap: boolean;

  /**
   * Whether to block movement that would cause collision.
   *
   * When true (and allowOverlap is false):
   * - Dragging into another item is blocked (item snaps back)
   * - Other items are NOT pushed away
   * - Only affects movement, not compaction
   *
   * Use with noCompactor for: fixed grids, slot-based layouts
   *
   * Note: Has no effect when allowOverlap is true.
   */
  preventCollision?: boolean;

  /**
   * Compact the entire layout.
   * Called after any layout change to fill gaps.
   *
   * @param layout - Array of layout items (clone before mutating!)
   * @param cols - Number of grid columns
   * @returns New compacted layout
   */
  compact(layout: Layout, cols: number): Layout;
}

import { cloneLayout, cloneLayoutItem, getStatics, bottom } from "react-grid-layout/core";

const gravityCompactor: Compactor = {
  type: "gravity",
  allowOverlap: false,

  compact(layout, cols) {
    const statics = getStatics(layout);
    const maxY = 100; // arbitrary max height
    const out = [];

    // Sort by Y descending (process bottom items first)
    const sorted = [...layout].sort((a, b) => b.y - a.y);

    for (const item of sorted) {
      const l = cloneLayoutItem(item);

      if (!l.static) {
        // Move down as far as possible
        while (l.y < maxY && !collides(l, statics)) {
          l.y++;
        }
        l.y--; // Back up one
      }

      out.push(l);
    }

    return out;
  }
};

// Usage
<GridLayout compactor={gravityCompactor} />

const singleRowCompactor: Compactor = {
  type: "shelf",
  allowOverlap: false,

  compact(layout, cols) {
    let x = 0;
    const out = [];

    // Sort by original X position
    const sorted = [...layout].sort((a, b) => a.x - b.x);

    for (const item of sorted) {
      const l = cloneLayoutItem(item);
      if (!l.static) {
        l.x = x;
        l.y = 0; // All items on row 0
        x += l.w;

        // Wrap to next row if overflow
        if (x > cols) {
          l.x = 0;
          x = l.w;
        }
      }
      out.push(l);
    }

    return out;
  }
};

import {
  resolveCompactionCollision, // Move items to resolve overlaps
  compactItemVertical, // Compact one item upward
  compactItemHorizontal, // Compact one item leftward
  getFirstCollision, // Find first collision
  collides, // Check if two items collide
  getStatics, // Get static items from layout
  cloneLayout, // Clone layout array
  cloneLayoutItem // Clone single item
} from "react-grid-layout/core";

interface PositionStrategy {
  /** Type identifier */
  type: "transform" | "absolute" | string;

  /** Scale factor for coordinate calculations */
  scale: number;

  /**
   * Generate CSS styles for positioning an item.
   *
   * @param pos - Position with top, left, width, height in pixels
   * @returns CSS properties object
   */
  calcStyle(pos: Position): React.CSSProperties;

  /**
   * Calculate drag position from mouse coordinates.
   * Used during drag to convert screen coords to grid coords.
   *
   * @param clientX - Mouse X position
   * @param clientY - Mouse Y position
   * @param offsetX - Offset from item left edge
   * @param offsetY - Offset from item top edge
   * @returns Calculated left/top position
   */
  calcDragPosition(
    clientX: number,
    clientY: number,
    offsetX: number,
    offsetY: number
  ): { left: number; top: number };
}

const createRotatedStrategy = (angleDegrees: number): PositionStrategy => {
  const angleRad = (angleDegrees * Math.PI) / 180;
  const cos = Math.cos(angleRad);
  const sin = Math.sin(angleRad);

  return {
    type: "rotated",
    scale: 1,

    calcStyle(pos) {
      // Apply rotation to position
      const rotatedX = pos.left * cos - pos.top * sin;
      const rotatedY = pos.left * sin + pos.top * cos;

      return {
        transform: `translate(${rotatedX}px, ${rotatedY}px)`,
        width: `${pos.width}px`,
        height: `${pos.height}px`,
        position: "absolute"
      };
    },

    calcDragPosition(clientX, clientY, offsetX, offsetY) {
      // Reverse the rotation for drag calculations
      const x = clientX - offsetX;
      const y = clientY - offsetY;

      return {
        left: x * cos + y * sin,
        top: -x * sin + y * cos
      };
    }
  };
};

// Usage: grid inside a rotated container
<div style={{ transform: 'rotate(45deg)' }}>
  <GridLayout positionStrategy={createRotatedStrategy(45)} />
</div>

const create3DStrategy = (
  perspective: number,
  rotateX: number
): PositionStrategy => ({
  type: "3d",
  scale: 1,

  calcStyle(pos) {
    return {
      transform: `
        perspective(${perspective}px)
        rotateX(${rotateX}deg)
        translate3d(${pos.left}px, ${pos.top}px, 0)
      `,
      width: `${pos.width}px`,
      height: `${pos.height}px`,
      position: "absolute",
      transformStyle: "preserve-3d"
    };
  },

  calcDragPosition(clientX, clientY, offsetX, offsetY) {
    // Adjust for perspective foreshortening
    const perspectiveFactor = 1 + clientY / perspective;
    return {
      left: (clientX - offsetX) / perspectiveFactor,
      top: (clientY - offsetY) / perspectiveFactor
    };
  }
});

interface GridBackgroundProps {
  // Required - must match your GridLayout config
  width: number; // Container width
  cols: number; // Number of columns
  rowHeight: number; // Row height in pixels

  // Optional
  margin?: [number, number]; // Gap between cells (default: [10, 10])
  containerPadding?: [number, number] | null; // Container padding (default: uses margin)
  rows?: number | "auto"; // Number of rows to display (default: 10)
  height?: number; // Used when rows="auto" to calculate row count
  color?: string; // Cell background color (default: "#e0e0e0")
  borderRadius?: number; // Cell border radius (default: 4)
  className?: string; // Additional CSS class
  style?: React.CSSProperties; // Additional inline styles
}

import { calcGridCellDimensions } from "react-grid-layout/core";

const dims = calcGridCellDimensions({
  width: 1200,
  cols: 12,
  rowHeight: 30,
  margin: [10, 10],
  containerPadding: [20, 20]
});

// dims = {
//   cellWidth: 88.33,  // Width of each cell
//   cellHeight: 30,     // Height of each cell (= rowHeight)
//   offsetX: 20,        // Left padding
//   offsetY: 20,        // Top padding
//   gapX: 10,           // Horizontal gap between cells
//   gapY: 10,           // Vertical gap between cells
//   cols: 12,           // Column count
//   containerWidth: 1200
// }