tailwind-grid-layout

Tailwind Grid Layout

A modern, lightweight grid layout system for React built with Tailwind CSS. A powerful alternative to react-grid-layout with full feature parity and a smaller bundle size.

Version 0.1.0 - First stable release

English | 한국어

Features

• 🎯 Full Feature Parity with react-grid-layout
• 🪶 Lightweight - Smaller bundle size using Tailwind CSS
• 🎨 Tailwind Native - Built with Tailwind CSS utilities
• 📱 Responsive - Works on all screen sizes
• 📱 Mobile Touch - Full touch device optimization with enhanced gesture support
  • Improved touch point accuracy
  • Long press gesture support
  • Prevent scroll-drag conflicts
  • Multi-touch prevention for stability
• 🔧 TypeScript - Full TypeScript support
• ⚡ Performance - Optimized rendering and animations
• 🧪 Well Tested - 100% test coverage

Installation

npm install tailwind-grid-layout
# or
yarn add tailwind-grid-layout
# or
pnpm add tailwind-grid-layout

Prerequisites

• React 19.1.0
• Tailwind CSS 4.1.8+ (v4 only - CSS-first configuration)
• Node.js 20.0.0+
• pnpm 10.11.0+

Tailwind CSS v4 Setup

This library requires Tailwind CSS v4 with its new CSS-first configuration approach. No JavaScript configuration file is needed.

/* In your main CSS file */
@import "tailwindcss";

/* Optional: Add custom theme configuration */
@theme {
  --color-grid-placeholder: oklch(0.7 0.15 210);
  --color-grid-handle: oklch(0.3 0.05 210);
}

Quick Start

import { GridContainer } from 'tailwind-grid-layout'

const items = [
  { id: '1', x: 0, y: 0, w: 2, h: 2 },
  { id: '2', x: 2, y: 0, w: 2, h: 2 },
  { id: '3', x: 0, y: 2, w: 4, h: 2 }
]

function App() {
  return (
    <GridContainer
      items={items}
      cols={12}
      rowHeight={60}
      onLayoutChange={(newLayout) => console.log(newLayout)}
    >
      {(item) => (
        <div className="bg-blue-500 text-white p-4 rounded">
          Item {item.id}
        </div>
      )}
    </GridContainer>
  )
}

Testing

# Run tests
pnpm test

# Watch mode
pnpm test:watch

# Coverage report
pnpm test:coverage

Test Coverage

This library maintains 100% test coverage:

• ✅ Lines: 100%
• ✅ Statements: 100%
• ✅ Functions: 100%
• ✅ Branches: 100%

Props Reference

GridContainer Props

Prop	Type	Default	Description
items	GridItem[]	required	Array of grid items with position and size
children	(item: GridItem) => ReactNode	required	Render function for grid items
cols	number	12	Number of columns in the grid
rowHeight	number	60	Height of each row in pixels
gap	number	16	Gap between grid items in pixels
margin	[number, number]	[gap, gap]	Margin between items [horizontal, vertical]
containerPadding	[number, number]	[16, 16]	Padding inside the grid container [horizontal, vertical]
maxRows	number	-	Maximum number of rows
isDraggable	boolean	true	Enable/disable dragging
isResizable	boolean	true	Enable/disable resizing
preventCollision	boolean	false	Prevent items from colliding
allowOverlap	boolean	false	Allow items to overlap
isBounded	boolean	true	Keep items within container bounds
compactType	'vertical' | 'horizontal' | null	'vertical'	Compaction type
resizeHandles	Array<'s' | 'w' | 'e' | 'n' | 'sw' | 'nw' | 'se' | 'ne'>	['se']	Resize handle positions
draggableCancel	string	-	CSS selector for elements that should not trigger drag
draggableHandle	string	-	CSS selector for drag handle
autoSize	boolean	true	Container height adjusts to fit all items
verticalCompact	boolean	true	DEPRECATED: Use compactType
transformScale	number	1	Scale factor for drag/resize when zoomed
droppingItem	Partial<GridItem>	-	Preview item while dragging from outside
className	string	-	Additional CSS classes for the container
style	React.CSSProperties	-	Inline styles for the container
onLayoutChange	(layout: GridItem[]) => void	-	Callback when layout changes
onDragStart	(layout, oldItem, newItem, placeholder, e, element) => void	-	Drag start callback
onDrag	(layout, oldItem, newItem, placeholder, e, element) => void	-	Drag callback
onDragStop	(layout, oldItem, newItem, placeholder, e, element) => void	-	Drag stop callback
onResizeStart	(layout, oldItem, newItem, placeholder, e, element) => void	-	Resize start callback
onResize	(layout, oldItem, newItem, placeholder, e, element) => void	-	Resize callback
onResizeStop	(layout, oldItem, newItem, placeholder, e, element) => void	-	Resize stop callback

GridItem Properties

Property	Type	Required	Description
id	string	✓	Unique identifier for the item
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
minH	number	-	Minimum height
maxW	number	-	Maximum width
maxH	number	-	Maximum height
isDraggable	boolean	-	Override container's isDraggable
isResizable	boolean	-	Override container's isResizable
static	boolean	-	Make item static (unmovable/unresizable)
className	string	-	Additional CSS classes for the item

ResponsiveGridContainer Props

Prop	Type	Default	Description
layouts	BreakpointLayouts	required	Object with layouts for each breakpoint
breakpoints	{ [breakpoint: string]: number }	{ lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 }	Minimum widths for each breakpoint
cols	{ [breakpoint: string]: number }	{ lg: 12, md: 10, sm: 6, xs: 4, xxs: 2 }	Number of columns for each breakpoint
onLayoutChange	(layout: GridItem[], layouts: BreakpointLayouts) => void	-	Called when layout changes with current layout and all layouts
onBreakpointChange	(newBreakpoint: string, cols: number) => void	-	Called when breakpoint changes
width	number	-	Container width (provided by WidthProvider)
...GridContainerProps	-	-	All other GridContainer props except items, cols, onLayoutChange

Comparison with react-grid-layout

Feature	react-grid-layout	tailwind-grid-layout	Notes
Core Features
Drag & Drop	✅	✅	Full support
Resize	✅	✅	8-direction resize
Collision Detection	✅	✅	50% overlap rule
Auto-compaction	✅	✅	Vertical, horizontal, or none
Static Items	✅	✅	Full support
Bounded Movement	✅	✅	Keep items in bounds
Layout Options
Responsive Breakpoints	✅	✅	Real-time responsive layouts with ResizeObserver
Persist Layout	✅	✅	Via onLayoutChange
Min/Max Dimensions	✅	✅	Full support
Prevent Collision	✅	✅	Full support
Allow Overlap	✅	✅	Full support
Events
Layout Change	✅	✅	Full support
Drag Events	✅	✅	Start, move, stop
Resize Events	✅	✅	Start, resize, stop
Drop from Outside	✅	✅	Full support with DroppableGridContainer
Styling
CSS-in-JS	✅	❌	Uses Tailwind
Custom Classes	✅	✅	Full support
Animations	✅	✅	Tailwind transitions
Performance
Bundle Size	~30KB	~22KB (gzip)	Smaller bundle
Dependencies	React only	React + Tailwind
Tree-shaking	✅	✅	Full support

Advanced Examples

With Custom Drag Handle

<GridContainer items={items}>
  {(item) => (
    <div className="bg-white rounded-lg shadow p-4">
      <div className="cursor-move p-2 bg-gray-100 rounded" data-drag-handle>
        <GripIcon className="w-4 h-4" />
      </div>
      <div className="p-4">
        Content for {item.id}
      </div>
    </div>
  )}
</GridContainer>

Static Items

const items = [
  { id: '1', x: 0, y: 0, w: 4, h: 2, static: true }, // This item cannot be moved
  { id: '2', x: 4, y: 0, w: 4, h: 2 },
]

Responsive Breakpoints

import { ResponsiveGridContainer, WidthProvider } from 'tailwind-grid-layout'

// Define layouts for each breakpoint
const layouts = {
  lg: [
    { id: '1', x: 0, y: 0, w: 6, h: 2 },
    { id: '2', x: 6, y: 0, w: 6, h: 2 },
    { id: '3', x: 0, y: 2, w: 4, h: 2 },
    { id: '4', x: 4, y: 2, w: 8, h: 2 }
  ],
  md: [
    { id: '1', x: 0, y: 0, w: 10, h: 2 },
    { id: '2', x: 0, y: 2, w: 10, h: 2 },
    { id: '3', x: 0, y: 4, w: 5, h: 2 },
    { id: '4', x: 5, y: 4, w: 5, h: 2 }
  ],
  sm: [
    { id: '1', x: 0, y: 0, w: 6, h: 2 },
    { id: '2', x: 0, y: 2, w: 6, h: 2 },
    { id: '3', x: 0, y: 4, w: 6, h: 2 },
    { id: '4', x: 0, y: 6, w: 6, h: 2 }
  ],
  xs: [
    { id: '1', x: 0, y: 0, w: 4, h: 2 },
    { id: '2', x: 0, y: 2, w: 4, h: 2 },
    { id: '3', x: 0, y: 4, w: 4, h: 2 },
    { id: '4', x: 0, y: 6, w: 4, h: 2 }
  ],
  xxs: [
    { id: '1', x: 0, y: 0, w: 2, h: 2 },
    { id: '2', x: 0, y: 2, w: 2, h: 2 },
    { id: '3', x: 0, y: 4, w: 2, h: 2 },
    { id: '4', x: 0, y: 6, w: 2, h: 2 }
  ]
}

// Option 1: Manual width tracking
function ResponsiveExample() {
  const [currentBreakpoint, setCurrentBreakpoint] = useState('lg')
  
  return (
    <ResponsiveGridContainer
      layouts={layouts}
      onBreakpointChange={(breakpoint) => {
        setCurrentBreakpoint(breakpoint)
        console.log(`Switched to ${breakpoint} breakpoint`)
      }}
      onLayoutChange={(layout, allLayouts) => {
        // Save layouts to state or backend
        console.log('Layout changed:', allLayouts)
      }}
    >
      {(item) => (
        <div className="bg-blue-500 text-white p-4 rounded">
          Item {item.id}
        </div>
      )}
    </ResponsiveGridContainer>
  )
}

// Option 2: Using WidthProvider for automatic width detection
const ResponsiveGridWithWidth = WidthProvider(ResponsiveGridContainer)

function App() {
  return (
    <ResponsiveGridWithWidth
      layouts={layouts}
      // Custom breakpoints (optional)
      breakpoints={{ lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 }}
      // Custom column configuration (optional)
      cols={{ lg: 12, md: 10, sm: 6, xs: 4, xxs: 2 }}
    >
      {(item) => <div>Item {item.id}</div>}
    </ResponsiveGridWithWidth>
  )
}

Drag and Drop from Outside

import { DroppableGridContainer } from 'tailwind-grid-layout'

<DroppableGridContainer
  items={items}
  onDrop={(newItem) => setItems([...items, newItem])}
  droppingItem={{ w: 2, h: 2 }} // Default size for dropped items
>
  {(item) => <div>Dropped Item {item.id}</div>}
</DroppableGridContainer>

Custom Resize Handles

<GridContainer
  items={items}
  resizeHandles={['se', 'sw', 'ne', 'nw']} // Enable corner handles only
>
  {(item) => <div>Item {item.id}</div>}
</GridContainer>

Prevent Collision

<GridContainer
  items={items}
  preventCollision={true} // Items cannot overlap
  allowOverlap={false}
>
  {(item) => <div>Item {item.id}</div>}
</GridContainer>

Bounded Grid with Max Rows

<GridContainer
  items={items}
  isBounded={true}
  maxRows={10}
>
  {(item) => <div>Item {item.id}</div>}
</GridContainer>

AutoSize Container

<GridContainer
  items={items}
  autoSize={true} // Container height adjusts automatically
>
  {(item) => <div>Item {item.id}</div>}
</GridContainer>

// With fixed height
<div style={{ height: 400, overflow: 'auto' }}>
  <GridContainer
    items={items}
    autoSize={false}
    style={{ height: '100%' }}
  >
    {(item) => <div>Item {item.id}</div>}
  </GridContainer>
</div>

Real-time Responsive Updates

The responsive grid automatically updates layouts when the window is resized, with debounced handling for optimal performance:

import { ResponsiveGridContainer } from 'tailwind-grid-layout'

function DashboardExample() {
  const [layouts, setLayouts] = useState({
    lg: dashboardLayoutLg,
    md: dashboardLayoutMd,
    sm: dashboardLayoutSm,
    xs: dashboardLayoutXs,
    xxs: dashboardLayoutXxs
  })
  const [currentBreakpoint, setCurrentBreakpoint] = useState('')
  const [currentCols, setCurrentCols] = useState(12)

  return (
    <>
      {/* Visual breakpoint indicator */}
      <div className="mb-4 p-2 bg-green-100 rounded">
        Current: {currentBreakpoint} ({currentCols} columns)
      </div>
      
      <ResponsiveGridContainer
        layouts={layouts}
        onLayoutChange={(layout, allLayouts) => {
          setLayouts(allLayouts)
        }}
        onBreakpointChange={(breakpoint, cols) => {
          setCurrentBreakpoint(breakpoint)
          setCurrentCols(cols)
        }}
        rowHeight={100}
        gap={16}
        containerPadding={[16, 16]}
      >
        {(item) => (
          <Card key={item.id}>
            <CardHeader>
              <CardTitle>{item.title}</CardTitle>
            </CardHeader>
            <CardContent>
              {item.content}
            </CardContent>
          </Card>
        )}
      </ResponsiveGridContainer>
    </>
  )
}

Dropping Item Preview

<DroppableGridContainer
  items={items}
  droppingItem={{ w: 4, h: 2 }} // Shows preview while dragging
  onDrop={(newItem) => setItems([...items, newItem])}
>
  {(item) => <div>Item {item.id}</div>}
</DroppableGridContainer>

Layout Utilities

generateLayouts

Generate identical layouts for all breakpoints from a single layout definition.

import { generateLayouts } from 'tailwind-grid-layout'

const items = [
  { id: '1', x: 0, y: 0, w: 4, h: 2 },
  { id: '2', x: 4, y: 0, w: 4, h: 2 }
]

// Creates layouts for lg, md, sm, xs, xxs with identical positioning
const layouts = generateLayouts(items)

generateResponsiveLayouts

Automatically adjust layouts to fit different column counts per breakpoint.

import { generateResponsiveLayouts } from 'tailwind-grid-layout'

const items = [
  { id: '1', x: 0, y: 0, w: 12, h: 2 },
  { id: '2', x: 0, y: 2, w: 6, h: 2 }
]

// Adjusts item widths and positions to fit column constraints
const layouts = generateResponsiveLayouts(items, {
  lg: 12,
  md: 10, 
  sm: 6,
  xs: 4,
  xxs: 2
})

WidthProvider HOC

Automatically provides container width to ResponsiveGridContainer using ResizeObserver for optimal performance.

import { ResponsiveGridContainer, WidthProvider } from 'tailwind-grid-layout'

const ResponsiveGridWithWidth = WidthProvider(ResponsiveGridContainer)

// Basic usage
<ResponsiveGridWithWidth
  layouts={layouts}
  rowHeight={100}
>
  {(item) => <div>Item {item.id}</div>}
</ResponsiveGridWithWidth>

// With measureBeforeMount to prevent layout shift on initial render
<ResponsiveGridWithWidth
  layouts={layouts}
  measureBeforeMount={true}
  rowHeight={100}
>
  {(item) => <div>Item {item.id}</div>}
</ResponsiveGridWithWidth>

// WidthProvider features:
// - Uses ResizeObserver for efficient width detection
// - Falls back to window resize events if ResizeObserver is unavailable
// - Handles SSR correctly with measureBeforeMount option
// - Debounced resize handling (150ms) for better performance

Styling Guide

Using with Tailwind CSS

The library is built to work seamlessly with Tailwind CSS:

<GridContainer items={items} className="bg-gray-50 rounded-lg">
  {(item) => (
    <div className="bg-white rounded-lg shadow-md hover:shadow-lg transition-shadow">
      <div className="p-4">
        <h3 className="text-lg font-semibold">Item {item.id}</h3>
      </div>
    </div>
  )}
</GridContainer>

Custom Placeholders

The drag and resize placeholders can be styled via CSS:

/* Drag placeholder */
.tailwind-grid-layout .drag-placeholder {
  background: rgba(59, 130, 246, 0.15);
  border: 2px dashed rgb(59, 130, 246);
}

/* Resize placeholder */
.tailwind-grid-layout .resize-placeholder {
  background: rgba(59, 130, 246, 0.1);
  border: 2px dashed rgb(59, 130, 246);
}

Performance Optimizations

• Hardware Acceleration: Uses CSS transforms with will-change
• Gesture Debouncing: Optimized touch event handling
  • Touch events are debounced at 16ms (60fps)
  • Minimizes unnecessary re-renders
• Memory Management: Proper cleanup of event listeners
• Bundle Splitting: Tree-shakable exports
• ResizeObserver: Efficient container width detection
• Animation Control: Transitions disabled during interactions

Touch Event Handling

Optimized touch event handling for best performance on mobile devices:

• Passive Listeners: Uses passive touch events for improved scroll performance
• Gesture Recognition: Accurately distinguishes between tap, long press, and drag gestures
• Momentum Scrolling: Natural momentum effects after touch release
• Pointer Events API: Unified handling for touch, mouse, and pen input

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)
• Mobile Safari (iOS 12+)
• Chrome Mobile (Android 7+)
• ResizeObserver support required for optimal performance

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT © Seungwoo, Lee

Acknowledgments

This library is inspired by react-grid-layout and aims to provide a modern, Tailwind-first alternative.