Table of Contents

Demos

Projects Using React-Grid-Layout

Features

Installation

npm install react-grid-layout

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

Usage

importGridLayoutfrom"react-grid-layout";classMyFirstGridextendsReact.Component{render(){// layout is an array of objects, see the demo for more complete usageconstlayout=[{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(<GridLayoutclassName="layout"layout={layout}cols={12}rowHeight={30}width={1200}><divkey="a">a</div><divkey="b">b</div><divkey="c">c</div></GridLayout>);}}

importGridLayoutfrom"react-grid-layout";classMyFirstGridextendsReact.Component{render(){return(<GridLayoutclassName="layout"cols={12}rowHeight={30}width={1200}><divkey="a"data-grid={{x:0,y:0,w:1,h:2,static:true}}>          a</div><divkey="b"data-grid={{x:1,y:0,w:3,h:2,minW:2,maxW:4}}>          b</div><divkey="c"data-grid={{x:4,y:0,w:1,h:2}}>          c</div></GridLayout>);}}

Usage without Browserify/Webpack

Responsive Usage

import{ResponsiveasResponsiveGridLayout}from"react-grid-layout";classMyResponsiveGridextendsReact.Component{render(){// {lg: layout1, md: layout2, ...}constlayouts=getLayoutsFromSomewhere();return(<ResponsiveGridLayoutclassName="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}}><divkey="1">1</div><divkey="2">2</div><divkey="3">3</div></ResponsiveGridLayout>);}}

Providing Grid Width

import{Responsive,WidthProvider}from"react-grid-layout";constResponsiveGridLayout=WidthProvider(Responsive);classMyResponsiveGridextendsReact.Component{render(){// {lg: layout1, md: layout2, ...}varlayouts=getLayoutsFromSomewhere();return(<ResponsiveGridLayoutclassName="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}}><divkey="1">1</div><divkey="2">2</div><divkey="3">3</div></ResponsiveGridLayout>);}}

Grid Layout Props

//// Basic props//// This allows setting the initial width on the server side.// This is required unless using the HOC <WidthProvider> or similarwidth:number,// If true, the container height swells and contracts to fit contentsautoSize: ?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.// .react-resizable-handle" is always prepended to this value.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='',// Compaction type.compactType: ?('vertical'|'horizontal'|null)='vertical';// Layout is an array of objects with the format:// 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 using the `i` prop.layout: ?Array<{i?:string,x:number,y:number,w:number,h:number}>=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 pxcontainerPadding: ?[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 elementdroppingItem?:{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 performanceuseCSSTransforms: ?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 can be placed one over the other.// If set, implies `preventCollision`.allowOverlap: ?boolean=false,// If true, grid items won't change position when being// dragged over. If `allowOverlap` is still false,// this simply won't allow one to drop on an existing object.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=568313isDroppable: ?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)//// Note that changing this property dynamically does not work due to a restriction in react-resizable.resizeHandles: ?Array<'s'|'w'|'e'|'n'|'sw'|'nw'|'se'|'ne'>=['se'],// Custom component for resize handles// See `handle` as used in https://github.com/react-grid-layout/react-resizable#resize-handle// Your component should have the class `.react-resizable-handle`, or you should add your custom// class to the `draggableCancel` prop.resizeHandle?:ReactElement<any>|((resizeHandleAxis:ResizeHandleAxis,ref:ReactRef<HTMLElement>)=>ReactElement<any>),//// 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'.//typeItemCallback=(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,//// Dropover functionality//// Calls when an element has been dropped into the grid from outside.onDrop:(layout:Layout,item: ?LayoutItem,e:Event)=>void,// Calls when an element is being dragged over the grid from outside as above.// This callback should return an object to dynamically change the droppingItem size// Return false to short-circuit the dragoveronDropDragOver:(e:DragOverEvent)=> ?({|w?:number,h?:number|}|false),// 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.// Note that this type is React.Ref<HTMLDivElement> in TypeScript, Flow has a bug here// https://github.com/facebook/flow/issues/8671#issuecomment-862634865innerRef:{current:null|HTMLDivElement},

Responsive Grid Layout Props

// {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<breakpoints>]:[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<breakpoints>]:[number,number]},// layouts is an object mapping breakpoints to layouts.// e.g. {lg: Layout, md: Layout, ...}layouts:{[key:$Keys<breakpoints>]:Layout},//// Callbacks//// Calls back with breakpoint and new # colsonBreakpointChange:(newBreakpoint:string,newCols:number)=>void,// Callback so you can save the layout.// AllLayouts are keyed by breakpoint.onLayoutChange:(currentLayout:Layout,allLayouts:{[key:$Keys<breakpoints>]: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

{// A string corresponding to the component keyi:string,// These are all in grid units, not pixelsx: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.// As of RGL >= 1.4.0, resizing on any corner works just fine!resizeHandles?: ?Array<'s'|'w'|'e'|'n'|'sw'|'nw'|'se'|'ne'>=['se']// If true and draggable, item will be moved only within grid.isBounded: ?boolean=false}

Grid Item Heights and Widths

Performance

// 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));}// ...

functionMyGrid(props){constchildren=React.useMemo(()=>{returnnewArray(props.count).fill(undefined).map((val,idx)=>{return<divkey={idx}data-grid={{x:idx,y:1,w:1,h:1}}/>;});},[props.count]);return<ReactGridLayoutcols={12}>{children}</ReactGridLayout>;}

React Hooks Performance

constResponsiveReactGridLayout=useMemo(()=>WidthProvider(Responsive),[]);

Custom Child Components and Draggable Handles

constCustomGridItemComponent=React.forwardRef(({style, className, onMouseDown, onMouseUp, onTouchEnd, children, ...props},ref)=>{return(<divstyle={{/* styles */, ...style}}className={className}ref={ref}onMouseDown={onMouseDown}onMouseUp={onMouseUp}onTouchEnd={onTouchEnd}>{/* Some other content */}{children}{/* Make sure to include children to add resizable handle */}</div>);})

Contribute

TODO List