React-Grid-Layout

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

Summary

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. Basic
2. No Dragging/Resizing (Layout Only)
3. Messy Layout Autocorrect
4. Layout Defined on Children
5. Static Elements
6. Adding/Removing Elements
7. Saving Layout to LocalStorage
8. Saving a Responsive Layout to LocalStorage

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

Usage

Use ReactGridLayout like any other component.

render: function() {
  // layout is an array of objects, see the demo
  var initialLayout = getOrGenerateLayout(); 
  return (
    <ReactGridLayout className="layout" initialLayout={initialLayout} 
      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:

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>
  )
}

Responsive Usage

To make RGL responsive, supply a map as the cols prop:

render: function() {
  return (
    <ReactGridLayout className="layout" initialLayouts={...} 
      cols={{lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0}}>
      <div key={1}>1</div>
      <div key={2}>2</div>
      <div key={3}>3</div>
    </ReactGridLayout>
  )
}

You have a choice when in responsive mode: you can simply supply an single layout via initialLayout, or multiple layouts in a map via initialLayouts.

When using initialLayouts, 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.

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,

// Can be specified as a single number or a {breakpoint: cols} map.
// If a map is provided, RGL becomes responsive and uses a separate layout
// per breakpoint.
cols: React.PropTypes.oneOfType([
  React.PropTypes.object,
  React.PropTypes.number
]),

// A selector for the draggable handler
handle: React.PropTypes.string,

// Layout is an array of object with the format:
// {x: Number, y: Number, w: Number, h: Number}
initialLayout: React.PropTypes.array,

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

// This allows setting this on the server side
initialWidth: React.PropTypes.number,

// 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,

// 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
// 

// 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,

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.

// 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,

Grid Layout Defaults

{
  autoSize: true,
  breakpoints: {lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0},
  cols: 10, 
  rowHeight: 150,
  initialWidth: 1280,
  margin: [10, 10],
  isDraggable: true,
  isResizable: true,
  listenToWindowResize: 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