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

Acknowledgments

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

Name		Name	Last commit message	Last commit date
Latest commit History 58 Commits
.github/workflows		.github/workflows
.storybook		.storybook
docs		docs
examples		examples
scripts		scripts
src		src
stories		stories
.gitignore		.gitignore
.npmignore		.npmignore
.npmrc		.npmrc
.releaserc.json		.releaserc.json
AI_DEVELOPMENT_GUIDELINES.md		AI_DEVELOPMENT_GUIDELINES.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
DEVELOPMENT.md		DEVELOPMENT.md
LICENSE		LICENSE
NPM_SETUP.md		NPM_SETUP.md
README.ko.md		README.ko.md
README.md		README.md
VERCEL_DEPLOY_GUIDE.md		VERCEL_DEPLOY_GUIDE.md
check-types.sh		check-types.sh
components.json		components.json
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tailwind.config.ts		tailwind.config.ts
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts
vite.docs.config.ts		vite.docs.config.ts
vitest.config.ts		vitest.config.ts

License

Seungwoo321/tailwind-grid-layout

Folders and files

Latest commit

History

Repository files navigation

Tailwind Grid Layout

Features

Installation

Prerequisites

Tailwind CSS v4 Setup

Quick Start

Testing

Test Coverage

Props Reference

GridContainer Props

GridItem Properties

ResponsiveGridContainer Props

Comparison with react-grid-layout

Advanced Examples

With Custom Drag Handle

Static Items

Responsive Breakpoints

Drag and Drop from Outside

Custom Resize Handles

Prevent Collision

Bounded Grid with Max Rows

AutoSize Container

Real-time Responsive Updates

Dropping Item Preview

Layout Utilities

generateLayouts

generateResponsiveLayouts

WidthProvider HOC

Styling Guide

Using with Tailwind CSS

Custom Placeholders

Performance Optimizations

Touch Event Handling

Browser Support

Contributing

License

Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 11

Packages 0

Contributors 3

Uh oh!

Languages

Packages