React-Grid-Layout

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.

GIF from production usage on BitMEX.com

[Demo | Changelog | CodeSandbox Editable demo]

Table of Contents

• Demos
• Features
• Installation
• Usage
• Responsive Usage
• Providing Grid Width
• Grid Layout Props
• Responsive Grid Layout Props
• Grid Item Props
• User Recipes
• Performance
• Contribute
• TODO List

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)
13. Prevent Collision
14. Error Case
15. Toolbox
16. Drag From Outside
17. Bounded Layout
18. Resizable Handles

Projects Using React-Grid-Layout

• BitMEX
• AWS CloudFront Dashboards
• Grafana
• Metabase
• HubSpot
• ComNetViz
• Stoplight
• Reflect
• ez-Dashing
• Kibana
• Graphext
• Monday
• Quadency
• Hakkiri
• Ubidots

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
• Configurable packing: horizontal, vertical, or off
• 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 with CSS Transforms: on / off, note paint (green) as % of time

|Version | Compatibility | |----------------|------------------| | >= 0.17.0 | React 0.16 | | >= 0.11.3 | React 0.14 & v15 | | >= 0.10.0 | React 0.14 | | 0.8. - 0.9.2 | React 0.13 | | < 0.8 | React 0.12 |

Installation

Install the React-Grid-Layout package package using npm:

npm install react-grid-layout

Include the following stylesheets in your application:

/node_modules/react-grid-layout/css/styles.css
/node_modules/react-resizable/css/styles.css

Usage

Use ReactGridLayout like any other component. The following example below will produce a grid with three items where:

• users will not be able to drag or resize item

  a

• item

  b

  will be restricted to a minimum width of 2 grid blocks and a maximum width of 4 grid blocks
• users will be able to freely drag and resize item

  c

import GridLayout from 'react-grid-layout';

class MyFirstGrid extends React.Component {
  render() {
    // layout is an array of objects, see the demo for more complete usage
    const layout = [
      {i: 'a', x: 0, y: 0, w: 1, h: 2, static: true},
      {i: 'b', x: 1, y: 0, w: 3, h: 2, minW: 2, maxW: 4},
      {i: 'c', x: 4, y: 0, w: 1, h: 2}
    ];
    return (
      
        
a
        
b
        
c
      
    )
  }
}

You may also choose to set layout properties directly on the children:

import GridLayout from 'react-grid-layout';

class MyFirstGrid extends React.Component {
  render() {
    return (
      
        
a
        
b
        
c
      
    )
  }
}

Usage without Browserify/Webpack

A module usable in a

React

window.React

Responsive Usage

To make RGL responsive, use the

import { Responsive as ResponsiveGridLayout } from 'react-grid-layout';

class MyResponsiveGrid extends React.Component {
  render() {
    // {lg: layout1, md: layout2, ...}
    const layouts = getLayoutsFromSomewhere();
    return (
      
        
1
        
2
        
3
      
    )
  }
}

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

layouts

When using

layouts

You will also need to provide a

width

WidthProvider

It is possible to supply default mappings via the

data-grid

Providing Grid Width

Both

width

WidthProvider

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

const ResponsiveGridLayout = WidthProvider(Responsive);
class MyResponsiveGrid extends React.Component {
  render() {
    // {lg: layout1, md: layout2, ...}
    var layouts = getLayoutsFromSomewhere();
    return (
      
        
1
        
2
        
3
      
    )
  }
}

This allows you to easily replace

WidthProvider

WidthProvider

measureBeforeMount

true

WidthProvider

Have a more complicated layout?

WidthProvider

'resize'

Grid Layout Props

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

//
// Basic props
//

// This allows setting the initial width on the server side.
// This is required unless using the HOC  or similar
width: number,
// If true, the container height swells and contracts to fit contents
autoSize: ?boolean = true,
// Number of columns in this layout.
cols: ?number = 12,
// A CSS selector for tags that will not be draggable.
// For example: draggableCancel:'.MyNonDraggableAreaClassName'
// If you forget the leading . it will not work.
draggableCancel: ?string = '',
// A CSS selector for tags that will act as the draggable handle.
// For example: draggableHandle:'.MyDragHandleClassName'
// If you forget the leading . it will not work.
draggableHandle: ?string = '',
// If true, the layout will compact vertically
verticalCompact: ?boolean = true,
// Compaction type.
compactType: ?('vertical' | 'horizontal') = 'vertical';
// 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: ?array = null, // If not provided, use data-grid props on children
// Margin between items [x, y] in px.
margin: ?[number, number] = [10, 10],
// Padding inside the container [x, y] in px
containerPadding: ?[number, number] = margin,
// Rows have a static height, but you can change this based on breakpoints
// if you like.
rowHeight: ?number = 150,
// Configuration of a dropping element. Dropping element is a "virtual" element
// which appears when you drag over some element from outside.
// It can be changed by passing specific parameters:
//  i - id of an element
//  w - width of an element
//  h - height of an element
droppingItem?: { i: string, w: number, h: number }
//
// Flags
//
isDraggable: ?boolean = true,
isResizable: ?boolean = true,
isBounded: ?boolean = false,
// Uses CSS3 translate() instead of position top/left.
// This makes about 6x faster paint performance
useCSSTransforms: ?boolean = true,
// If parent DOM node of ResponsiveReactGridLayout or ReactGridLayout has "transform: scale(n)" css property,
// we should set scale coefficient to avoid render artefacts while dragging.
transformScale: ?number = 1,
// If true, grid items won't change position when being
// dragged over.
preventCollision: ?boolean = false;
// If true, droppable elements (with draggable={true} attribute)
// can be dropped on the grid. It triggers "onDrop" callback
// with position and event object as parameters.
// It can be useful for dropping an element in a specific position
//
// NOTE: In case of using Firefox you should add
// onDragStart={e => e.dataTransfer.setData('text/plain', '')} attribute
// along with draggable={true} otherwise this feature will work incorrect.
// onDragStart attribute is required for Firefox for a dragging initialization
// @see https://bugzilla.mozilla.org/show_bug.cgi?id=568313
isDroppable: ?boolean = false
// Defines which resize handles should be rendered
// Allows for any combination of:
// 's' - South handle (bottom-center)
// 'w' - West handle (left-center)
// 'e' - East handle (right-center)
// 'n' - North handle (top-center)
// 'sw' - Southwest handle (bottom-left)
// 'nw' - Northwest handle (top-left)
// 'se' - Southeast handle (bottom-right)
// 'ne' - Northeast handle (top-right)
resizeHandles: ?Array = ['se']
//
// Callbacks
//
// Callback so you can save the layout.
// Calls back with (currentLayout) after every drag or resize stop.
onLayoutChange: (layout: Layout) => void,
//
// All callbacks below have signature (layout, oldItem, newItem, placeholder, e, element).
// 'start' and 'stop' callbacks pass undefined for 'placeholder'.
//
type ItemCallback = (layout: Layout, oldItem: LayoutItem, newItem: LayoutItem,
                     placeholder: LayoutItem, e: MouseEvent, element: HTMLElement) => void;
// Calls when drag starts.
onDragStart: ItemCallback,
// Calls on each drag movement.
onDrag: ItemCallback,
// Calls when drag is complete.
onDragStop: ItemCallback,
// Calls when resize starts.
onResizeStart: ItemCallback,
// Calls when resize movement happens.
onResize: ItemCallback,
// Calls when resize is complete.
onResizeStop: ItemCallback,
// Calls when an element has been dropped into the grid from outside.
onDrop: (layout: Layout, item: ?LayoutItem, e: Event) => void
// Ref for getting a reference for the grid's wrapping div.
// You can use this instead of a regular ref and the deprecated `ReactDOM.findDOMNode()`` function.
innerRef: ?React.Ref

Responsive Grid Layout Props

The responsive grid layout can be used instead. It supports all of the props above, excepting

layout

// {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: ?Object = {lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0},

// # of cols. This is a breakpoint -> cols map, e.g. {lg: 12, md: 10, ...}
cols: ?Object = {lg: 12, md: 10, sm: 6, xs: 4, xxs: 2},
// margin (in pixels). Can be specified either as horizontal and vertical margin, e.g. [10, 10] or as a breakpoint -> margin map, e.g. `{lg: [10, 10], md: [10, 10], ...}.
margin: [number, number] | {[breakpoint: $Keys]: [number, number]}
// containerPadding (in pixels). Can be specified either as horizontal and vertical padding, e.g. [10, 10] or as a breakpoint -> containerPadding map, e.g. `{lg: [10, 10], md: [10, 10], ...}.
containerPadding: [number, number] | {[breakpoint: $Keys]: [number, number]}
// layouts is an object mapping breakpoints to layouts.
// e.g. {lg: Layout, md: Layout, ...}
layouts: {[key: $Keys]: Layout}
//
// Callbacks
//
// Calls back with breakpoint and new # cols
onBreakpointChange: (newBreakpoint: string, newCols: number) => void,
// Callback so you can save the layout.
// AllLayouts are keyed by breakpoint.
onLayoutChange: (currentLayout: Layout, allLayouts: {[key: $Keys]: Layout}) => void,
// Callback when the width changes, so you can modify the layout as needed.
onWidthChange: (containerWidth: number, margin: [number, number], cols: number, containerPadding: [number, number]) => void;

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

data-grid

Note that if a grid item is provided but incomplete (missing one of

x, y, w, or h

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

isDraggable: false

isDraggable: true

static: true

{

  // A string corresponding to the component key
  i: string,
  // These are all in grid units, not pixels
  x: number,
  y: number,
  w: number,
  h: number,
  minW: ?number = 0,
  maxW: ?number = Infinity,
  minH: ?number = 0,
  maxH: ?number = Infinity,
  // If true, equal to isDraggable: false, isResizable: false.
  static: ?boolean = false,
  // If false, will not be draggable. Overrides static.
  isDraggable: ?boolean = true,
  // If false, will not be resizable. Overrides static.
  isResizable: ?boolean = true,
  // By default, a handle is only shown on the bottom-right (southeast) corner.
  // Note that resizing from the top or left is generally not intuitive.
  resizeHandles?: ?Array = ['se']
  // If true and draggable, item will be moved only within grid.
  isBounded: ?boolean = false
}

Performance

shouldComponentUpdate

children

// lib/ReactGridLayout.jsx
// ...
shouldComponentUpdate(nextProps: Props, nextState: State) {
  return (
    // NOTE: this is almost always unequal. Therefore the only way to get better performance
    // from SCU is if the user intentionally memoizes children. If they do, and they can
    // handle changes properly, performance will increase.
    this.props.children !== nextProps.children ||
    !fastRGLPropsEqual(this.props, nextProps, isEqual) ||
    !isEqual(this.state.activeDrag, nextState.activeDrag)
  );
}
// ...

If you memoize your children, you can take advantage of this, and reap faster rerenders. For example:

function MyGrid(props) {
  const children = React.useMemo(() => {
    return new Array(props.count).fill(undefined).map((val, idx) => {
      return 
;
    });
  }, [props.count]);
  return {children};
}

Because the

children

Contribute

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

If you have a bug to report, please reproduce the bug in CodeSandbox to help us easily isolate it.

TODO List

• [x] Basic grid layout
• [x] Fluid grid layout
• [x] Grid packing
• [x] Draggable grid items
• [x] Live grid packing while dragging
• [x] Resizable grid items
• [x] Layouts per responsive breakpoint
• [x] Define grid attributes on children themselves (

  data-grid

  key)
• [x] Static elements
• [x] Persistent id per item for predictable localstorage restores, even when # items changes
• [x] Min/max w/h per item
• [ ] Resizable handles on other corners
• [ ] Configurable w/h per breakpoint