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.

Live Demo | Storybook

English | 한국어

Features

• Full Feature Parity with react-grid-layout
• Lightweight - Smaller bundle size (~15KB gzip)
• Tailwind Native - Built with Tailwind CSS v4
• Responsive - Works on all screen sizes
• Mobile Touch - Full touch device support
• TypeScript - Full TypeScript support
• Well Tested - 100% test coverage

Installation

npm install tailwind-grid-layout

Requirements

• React 19+
• Tailwind CSS 4.x

Quick Start

import { useState } from 'react'
import { GridContainer } from 'tailwind-grid-layout'
import type { GridItem } from 'tailwind-grid-layout'

const initialItems: GridItem[] = [
  { id: '1', x: 0, y: 0, w: 3, h: 2 },
  { id: '2', x: 3, y: 0, w: 5, h: 3 },
  { id: '3', x: 8, y: 0, w: 4, h: 2 },
]

function App() {
  const [items, setItems] = useState(initialItems)

  return (
    <GridContainer
      items={items}
      cols={12}
      rowHeight={80}
      gap={16}
      onLayoutChange={setItems}
    >
      {(item) => (
        <div className="bg-white rounded-xl p-4 shadow">
          Item {item.id}
        </div>
      )}
    </GridContainer>
  )
}

Components

GridContainer

Basic grid container with drag and resize support.

<GridContainer
  items={items}
  cols={12}
  rowHeight={80}
  gap={16}
  isDraggable={true}
  isResizable={true}
  resizeHandles={['se', 'sw', 'ne', 'nw', 'n', 's', 'e', 'w']}
  onLayoutChange={setItems}
>
  {(item) => <div>Item {item.id}</div>}
</GridContainer>

GridContainer Props

Prop	Type	Default	Description
items	GridItem[]	required	Array of grid items
children	(item: GridItem) => ReactNode	required	Render function for each item
cols	number	12	Number of columns
rowHeight	number	60	Height of each row in pixels
gap	number	16	Gap between items in pixels
margin	[number, number]	[gap, gap]	Margin [horizontal, vertical]
containerPadding	[number, number]	[16, 16]	Container padding [horizontal, vertical]
maxRows	number	undefined	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 direction
resizeHandles	ResizeHandle[]	['se']	Resize handle positions
draggableCancel	string	undefined	CSS selector for non-draggable elements
draggableHandle	string	undefined	CSS selector for drag handle
autoSize	boolean	true	Auto-adjust container height
preserveInitialHeight	boolean	false	Preserve initial layout height
transformScale	number	1	Transform scale for nested transforms
className	string	undefined	Additional CSS classes
style	CSSProperties	undefined	Additional inline styles

GridContainer Callbacks

Callback	Type	Description
onLayoutChange	(layout: GridItem[]) => void	Called when layout changes
onDragStart	(layout, oldItem, newItem, placeholder, e, element) => void	Called when drag starts
onDrag	(layout, oldItem, newItem, placeholder, e, element) => void	Called during drag
onDragStop	(layout, oldItem, newItem, placeholder, e, element) => void	Called when drag ends
onResizeStart	(layout, oldItem, newItem, placeholder, e, element) => void	Called when resize starts
onResize	(layout, oldItem, newItem, placeholder, e, element) => void	Called during resize
onResizeStop	(layout, oldItem, newItem, placeholder, e, element) => void	Called when resize ends

ResponsiveGridContainer

Responsive grid with breakpoint-based layouts.

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

const ResponsiveGrid = WidthProvider(ResponsiveGridContainer)

const layouts = {
  lg: [{ id: '1', x: 0, y: 0, w: 6, h: 2 }],
  md: [{ id: '1', x: 0, y: 0, w: 10, h: 2 }],
  sm: [{ id: '1', x: 0, y: 0, w: 6, h: 2 }],
}

<ResponsiveGrid
  layouts={layouts}
  breakpoints={{ lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 }}
  cols={{ lg: 12, md: 10, sm: 6, xs: 4, xxs: 2 }}
  onLayoutChange={(layout, layouts) => console.log(layouts)}
  onBreakpointChange={(breakpoint, cols) => console.log(breakpoint)}
>
  {(item) => <div>Item {item.id}</div>}
</ResponsiveGrid>

ResponsiveGridContainer Props

Inherits all GridContainer props except items, cols, and onLayoutChange.

Prop	Type	Default	Description
layouts	{ [breakpoint: string]: GridItem[] }	required	Layout for each breakpoint
breakpoints	{ [breakpoint: string]: number }	{ lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 }	Breakpoint widths
cols	{ [breakpoint: string]: number }	{ lg: 12, md: 10, sm: 6, xs: 4, xxs: 2 }	Columns per breakpoint
onLayoutChange	(layout: GridItem[], layouts: BreakpointLayouts) => void	undefined	Called when layout changes
onBreakpointChange	(breakpoint: string, cols: number) => void	undefined	Called when breakpoint changes
width	number	undefined	Container width (for WidthProvider)

DroppableGridContainer

Grid with external drag-and-drop support.

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

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

DroppableGridContainer Props

Inherits all GridContainer props except onDrop.

Prop	Type	Default	Description
droppingItem	Partial<GridItem>	{ w: 2, h: 2 }	Size of dropping item
onDrop	(item: GridItem) => void	undefined	Called when item is dropped

WidthProvider

HOC that provides width to ResponsiveGridContainer.

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

const ResponsiveGrid = WidthProvider(ResponsiveGridContainer)

// Or with options
const ResponsiveGrid = WidthProvider(ResponsiveGridContainer)

<ResponsiveGrid measureBeforeMount={true}>
  {/* ... */}
</ResponsiveGrid>

WidthProvider Props

Prop	Type	Default	Description
measureBeforeMount	boolean	false	Measure width before mounting

GridItem Properties

Property	Type	Required	Description
id	string	Yes	Unique identifier
x	number	Yes	X position in grid units
y	number	Yes	Y position in grid units
w	number	Yes	Width in grid units
h	number	Yes	Height in grid units
minW	number	No	Minimum width
maxW	number	No	Maximum width
minH	number	No	Minimum height
maxH	number	No	Maximum height
static	boolean	No	Make item unmovable and unresizable
isDraggable	boolean	No	Override container's isDraggable
isResizable	boolean	No	Override container's isResizable
className	string	No	Additional CSS class for item

Resize Handles

Available resize handle positions:

Handle	Position
n	North (top center)
s	South (bottom center)
e	East (right center)
w	West (left center)
ne	North-East (top right corner)
nw	North-West (top left corner)
se	South-East (bottom right corner)
sw	South-West (bottom left corner)

Utility Functions

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

// Generate layout from items
const layout = generateLayouts(items)

// Generate responsive layouts
const responsiveLayouts = generateResponsiveLayouts(items, breakpoints, cols)

Comparison with react-grid-layout

Feature	react-grid-layout	tailwind-grid-layout
Bundle Size	~30KB	~15KB
Tailwind Native	No	Yes
TypeScript	Yes	Yes
Touch Support	Yes	Yes
Responsive	Yes	Yes
External CSS	Required	Not needed

License

MIT © Seungwoo, Lee