react-grid-layout

What is react-grid-layout?

react-grid-layout is a powerful library for creating dynamic and responsive grid layouts in React applications. It allows developers to create draggable, resizable, and responsive grid layouts with ease.

What are react-grid-layout's main functionalities?

Draggable Grid Items

This feature allows you to create grid items that can be dragged around within the grid. The layout array defines the position and size of each grid item.

import React from 'react';
import GridLayout from 'react-grid-layout';

const layout = [
  {i: 'a', x: 0, y: 0, w: 1, h: 2},
  {i: 'b', x: 1, y: 0, w: 3, h: 2},
  {i: 'c', x: 4, y: 0, w: 1, h: 2}
];

const MyFirstGrid = () => (
  <GridLayout className="layout" layout={layout} cols={12} rowHeight={30} width={1200}>
    <div key="a">A</div>
    <div key="b">B</div>
    <div key="c">C</div>
  </GridLayout>
);

export default MyFirstGrid;

Resizable Grid Items

This feature allows you to create grid items that can be resized by dragging their edges. The isResizable property in the layout array enables resizing for each grid item.

import React from 'react';
import GridLayout from 'react-grid-layout';

const layout = [
  {i: 'a', x: 0, y: 0, w: 1, h: 2, isResizable: true},
  {i: 'b', x: 1, y: 0, w: 3, h: 2, isResizable: true},
  {i: 'c', x: 4, y: 0, w: 1, h: 2, isResizable: true}
];

const MyFirstGrid = () => (
  <GridLayout className="layout" layout={layout} cols={12} rowHeight={30} width={1200}>
    <div key="a">A</div>
    <div key="b">B</div>
    <div key="c">C</div>
  </GridLayout>
);

export default MyFirstGrid;

Responsive Grid Layout

This feature allows you to create grid layouts that adapt to different screen sizes. The layouts object defines the layout for different breakpoints, making the grid responsive.

import React from 'react';
import { Responsive, WidthProvider } from 'react-grid-layout';

const ResponsiveGridLayout = WidthProvider(Responsive);

const layouts = {
  lg: [
    {i: 'a', x: 0, y: 0, w: 1, h: 2},
    {i: 'b', x: 1, y: 0, w: 3, h: 2},
    {i: 'c', x: 4, y: 0, w: 1, h: 2}
  ],
  md: [
    {i: 'a', x: 0, y: 0, w: 1, h: 2},
    {i: 'b', x: 1, y: 0, w: 2, h: 2},
    {i: 'c', x: 3, y: 0, w: 1, h: 2}
  ]
};

const MyResponsiveGrid = () => (
  <ResponsiveGridLayout className="layout" layouts={layouts} breakpoints={{lg: 1200, md: 996}} cols={{lg: 12, md: 10}}>
    <div key="a">A</div>
    <div key="b">B</div>
    <div key="c">C</div>
  </ResponsiveGridLayout>
);

export default MyResponsiveGrid;

Other packages similar to react-grid-layout

react-grid-system

react-grid-system provides a responsive grid layout system for React applications. It is simpler and more lightweight compared to react-grid-layout, focusing primarily on responsive design without built-in drag-and-drop or resizable functionalities.

react-masonry-component

react-masonry-component is a React wrapper for the Masonry layout library. It allows for creating dynamic grid layouts with a masonry-style arrangement. Unlike react-grid-layout, it does not support drag-and-drop or resizing but excels in creating Pinterest-like layouts.

react-flexbox-grid

react-flexbox-grid is a set of React components implementing flexboxgrid.css. It provides a grid system based on flexbox, which is highly responsive and easy to use. However, it lacks the drag-and-drop and resizable features found in react-grid-layout.

README

React-Grid-Layout

• Summary
• Changelog
• Demos
• Features
• Usage
• Responsive Usage
• Grid Layout Props
• Grid Item Props
• Grid Layout Defaults
• TODO List

Summary

Version	Compatibility
>= 0.10.0	React 0.14
0.8. - 0.9.2	React 0.13
< 0.8	React 0.12

View the Demo

React-Grid-Layout is a grid layout system much like Packery or Gridster, for React.

Unlike those systems, it is responsive and supports breakpoints. Breakpoint layouts can be provided by the user or autogenerated.

RGL is React-only and does not require jQuery.

If you have a feature request, please add it as an issue or make a pull request. See also the TODOs.

Demos

1. Showcase
2. Basic
3. No Dragging/Resizing (Layout Only)
4. Messy Layout Autocorrect
5. Layout Defined on Children
6. Static Elements
7. Adding/Removing Elements
8. Saving Layout to LocalStorage
9. Saving a Responsive Layout to LocalStorage
10. Minimum and Maximum Width/Height
11. Dynamic Minimum and Maximum Width/Height
12. No Vertical Compacting (Free Movement)

Projects based on React-Grid-Layout

• AWS CloudFront Dashboards
• Metabase
• HubSpot

Know of others? Create a PR to let me know!

Features

• 100% React - no jQuery
• Compatible with server-rendered apps
• Draggable widgets
• Resizable widgets
• Static widgets
• Vertical auto-packing
• Bounds checking for dragging and resizing
• Widgets may be added or removed without rebuilding grid
• Layout can be serialized and restored
• Responsive breakpoints
• Separate layouts per responsive breakpoint
• Grid Items placed using CSS Transforms
  • Performance: on / off, note paint (green) as % of time

Usage

Use ReactGridLayout like any other component.

var ReactGridLayout = require('react-grid-layout');
//...
render: function() {
  // layout is an array of objects, see the demo
  var layout = getOrGenerateLayout();
  return (
    <ReactGridLayout className="layout" layout={layout}
      cols={12} rowHeight={30}>
      <div key={1}>1</div>
      <div key={2}>2</div>
      <div key={3}>3</div>
    </ReactGridLayout>
  )
}

You can also set layout properties directly on the children:

var ReactGridLayout = require('react-grid-layout');
//...
render: function() {
  return (
    <ReactGridLayout className="layout" cols={12} rowHeight={30}>
      <div key="1" _grid={{x: 0, y: 0, w: 1, h: 2}}>1</div>
      <div key="2" _grid={{x: 1, y: 0, w: 1, h: 2}}>2</div>
      <div key="3" _grid={{x: 2, y: 0, w: 1, h: 2}}>3</div>
    </ReactGridLayout>
  )
}

Usage without Browserify/Webpack

A module usable in a <script> tag is included here. It uses a UMD shim and excludes React, so it must be otherwise available in your application, either via RequireJS or on window.React.

Responsive Usage

To make RGL responsive, use the <ResponsiveReactGridLayout> element:

var ResponsiveReactGridLayout = require('react-grid-layout').Responsive;
//...
render: function() {
  // {lg: layout1, md: layout2, ...}
  var layouts = getLayoutsFromSomewhere();
  return (
    <ResponsiveReactGridLayout className="layout" layouts={layouts}
      breakpoints={{lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0}}
      cols={{lg: 12, md: 10, sm: 6, xs: 4, xxs: 2}}>
      <div key={"1"}>1</div>
      <div key={"2"}>2</div>
      <div key={"3"}>3</div>
    </ResponsiveReactGridLayout>
  )
}

When in responsive mode, you should supply at least one breakpoint via the layouts property.

When using layouts, it is best to supply as many breakpoints as possible, especially the largest one. If the largest is provided, RGL will attempt to interpolate the rest.

For the time being, it is not possible to supply responsive mappings via the _grid property on individual items, but that is coming soon.

Providing grid width

Both <ResponsiveReactGridLayout> and <ReactGridLayout> take width to calculate positions on drag events. In simple cases a HOC <WidthProvider> can be used to automatically determine width upon initialization and window resize events.

var WidthProvider = require('react-grid-layout').WidthProvider;
var ResponsiveReactGridLayout = require('react-grid-layout').Responsive;
ResponsiveReactGridLayout = WidthProvider(ResponsiveReactGridLayout);

//...
render: function() {
  // {lg: layout1, md: layout2, ...}
  var layouts = getLayoutsFromSomewhere();
  return (
    <ResponsiveReactGridLayout className="layout" layouts={layouts}
      breakpoints={{lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0}}
      cols={{lg: 12, md: 10, sm: 6, xs: 4, xxs: 2}}>
      <div key={"1"}>1</div>
      <div key={"2"}>2</div>
      <div key={"3"}>3</div>
    </ResponsiveReactGridLayout>
  )
}

This allows you to easily replace <WidthProvider> with your own Provider HOC if you need more sophisticated logic.

Grid Layout Props

RGL supports the following properties (see the source for the final word on this):

//
// Basic props
//

// If true, the container height swells and contracts to fit contents
autoSize: React.PropTypes.bool,

// {name: pxVal}, e.g. {lg: 1200, md: 996, sm: 768, xs: 480}
breakpoints: React.PropTypes.object,

// Number of columns in this layout.
cols: React.PropTypes.number,

// A selector that will not be draggable.
draggableCancel: React.PropTypes.string,
// A selector for the draggable handler
draggableHandle: React.PropTypes.string,

// If true, the layout will compact vertically
verticalCompact: React.PropTypes.bool,

// Layout is an array of object with the format:
// {x: Number, y: Number, w: Number, h: Number}
// The index into the layout must match the key used on each item component.
// If you choose to use custom keys, you can specify that key in the layout
// array objects like so:
// {i: String, x: Number, y: Number, w: Number, h: Number}
layout: React.PropTypes.array,

// This allows setting the initial width on the server side.
width: React.PropTypes.number.isRequired,

// Margin between items [x, y] in px.
margin: React.PropTypes.array,

// Rows have a static height, but you can change this based on breakpoints
// if you like.
rowHeight: React.PropTypes.number,

//
// Flags
//
isDraggable: React.PropTypes.bool,
isResizable: React.PropTypes.bool,
// Uses CSS3 translate() instead of position top/left.
// This makes about 6x faster paint performance
useCSSTransforms: React.PropTypes.bool,

// If false, you should supply width yourself. Good if you want to debounce
// resize events or reuse a handler from somewhere else.
listenToWindowResize: React.PropTypes.bool,

//
// Callbacks
//

// Callback so you can save the layout.
// Calls back with (currentLayout) after every drag or resize stop.
onLayoutChange: React.PropTypes.func,

//
// All callbacks below have signature (layout, oldItem, newItem, placeholder, e, element).
// 'start' and 'stop' callbacks pass `undefined` for 'placeholder'.
//

// Calls when drag starts.
onDragStart: React.PropTypes.func,
// Calls on each drag movement.
onDrag: React.PropTypes.func,
// Calls when drag is complete.
onDragStop: React.PropTypes.func,
// Calls when resize starts.
onResizeStart: React.PropTypes.func,
// Calls when resize movement happens.
onResize: React.PropTypes.func,
// Calls when resize is complete.
onResizeStop: React.PropTypes.func

Responsive Grid Layout Props

The responsive grid layout can be used instead. It supports all of the props above, excepting layout. The new properties and changes are:

// {name: pxVal}, e.g. {lg: 1200, md: 996, sm: 768, xs: 480}
// Breakpoint names are arbitrary but must match in the cols and layouts objects.
breakpoints: React.PropTypes.object,

// # of cols. This is a breakpoint -> cols map, e.g. {lg: 12, md: 10, ...}
cols: React.PropTypes.object,

// layouts is an object mapping breakpoints to layouts.
// e.g. {lg: Layout, md: Layout, ...}
layouts: React.PropTypes.object

//
// Callbacks
//

// Calls back with breakpoint and new # cols
onBreakpointChange: React.PropTypes.func,

// Callback so you can save the layout.
// Calls back with (currentLayout, allLayouts). allLayouts are keyed by breakpoint.
onLayoutChange: React.PropTypes.func

// Callback when the width changes, so you can modify the layout as needed.
// Calls back with (containerWidth, margin, cols)
onWidthChange: React.Proptypes.func

Grid Item Props

RGL supports the following properties on grid items or layout items. When initializing a grid, build a layout array (as in the first example above), or attach this object as the _grid property to each of your child elements (as in the second example).

Note that if a grid item is provided but incomplete (missing one of x, y, w, or h), an error will be thrown so you can correct your layout.

If no properties are provided for a grid item, one will be generated with a width and height of 1.

You can set minimums and maximums for each dimension. This is for resizing; it of course has no effect if resizing is disabled. Errors will be thrown if your mins and maxes overlap incorrectly, or your initial dimensions are out of range.

Any GridItem properties defined directly on the layout item will take precedence over globally-set options. For example, if the layout has the property isDraggable: false, but the grid item has isDraggable: true, the item will be draggable.

{
  // These are all in grid units, not pixels
  x: React.PropTypes.number.isRequired,
  y: React.PropTypes.number.isRequired,
  w: React.PropTypes.number.isRequired,
  h: React.PropTypes.number.isRequired,
  minW: React.PropTypes.number,
  maxW: React.PropTypes.number,
  minH: React.PropTypes.number,
  maxH: React.PropTypes.number,

  // If true, equal to `isDraggable: false, isResizable: false`.
  static: React.PropTypes.bool,
  // If false, will not be draggable. Overrides `static`.
  isDraggable: React.PropTypes.bool,
  // If false, will not be resizable. Overrides `static`.
  isResizable: React.PropTypes.bool,

  className: React.PropTypes.string,
  // Selector for draggable handle
  handle: React.PropTypes.string,
  // Selector for draggable cancel (see react-draggable)
  cancel: React.PropTypes.string
}

Grid Layout Defaults

{
  autoSize: true,
  breakpoints: {lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0},
  cols: 10,
  rowHeight: 150,
  margin: [10, 10],
  minH: 1,
  minW: 1,
  maxH: Infinity,
  maxW: Infinity,
  isDraggable: true,
  isResizable: true,
  useCSSTransforms: true,
  listenToWindowResize: true,
  verticalCompact: true
}

TODO List

• Basic grid layout
• Fluid grid layout
• Grid packing
• Draggable grid items
• Live grid packing while dragging
• Resizable grid items
• Layouts per responsive breakpoint
• Define grid attributes on children themselves (_grid key)
• Static elements
• Persistent id per item for predictable localstorage restores, even when # items changes
• Min/max w/h per item
• Resizable handles on other corners
• Configurable w/h per breakpoint