react-grid-layout
Advanced tools
A draggable and resizable grid layout with responsive breakpoints, for React.
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.
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;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 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 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.
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]
Know of others? Create a PR to let me know!
| 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 |
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
Use ReactGridLayout like any other component. The following example below will produce a grid with three items where:
ab will be restricted to a minimum width of 2 grid blocks and a maximum width of 4 grid blockscimport 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 (
<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>
)
}
}
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 (
<GridLayout className="layout" cols={12} rowHeight={30} width={1200}>
<div key="a" data-grid={{x: 0, y: 0, w: 1, h: 2, static: true}}>a</div>
<div key="b" data-grid={{x: 1, y: 0, w: 3, h: 2, minW: 2, maxW: 4}}>b</div>
<div key="c" data-grid={{x: 4, y: 0, w: 1, h: 2}}>c</div>
</GridLayout>
)
}
}
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.
To make RGL responsive, use the <ResponsiveReactGridLayout> element:
import { Responsive as ResponsiveGridLayout } from 'react-grid-layout';
class MyResponsiveGrid extends React.Component {
render() {
// {lg: layout1, md: layout2, ...}
const layouts = getLayoutsFromSomewhere();
return (
<ResponsiveGridLayout 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>
</ResponsiveGridLayout>
)
}
}
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.
You will also need to provide a width, when using <ResponsiveReactGridLayout> it is suggested you use the HOC
WidthProvider as per the instructions below.
For the time being, it is not possible to supply responsive mappings via the data-grid property on individual
items, but that is coming soon.
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.
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 (
<ResponsiveGridLayout 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>
</ResponsiveGridLayout>
)
}
}
This allows you to easily replace WidthProvider with your own Provider HOC if you need more sophisticated logic.
WidthProvider accepts a single prop, measureBeforeMount. If true, WidthProvider will measure the
container's width before mounting children. Use this if you'd like to completely eliminate any resizing animation
on application/component mount.
Have a more complicated layout? WidthProvider is very simple and only
listens to window 'resize' events. If you need more power and flexibility, try the
SizeMe React HOC as an alternative to WidthProvider.
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 <WidthProvider> 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,
// 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
//
// 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 some element has been dropped
onDrop: (elemParams: { x: number, y: number, w: number, h: number, e: Event }) => void
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: ?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 # 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<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;
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 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 will take precedence over globally-set options. For
example, if the layout has the property isDraggable: false, but the grid item has the prop isDraggable: true, the item
will be draggable, even if the item is marked 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
}
<ReactGridLayout> has an optimized shouldComponentUpdate implementation, but it relies on the user memoizing the children array:
// 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() {
const children = React.useMemo((count) => {
return new Array(count).fill(undefined).map((val, idx) => {
return <div key={idx} data-grid={{x: idx, y: 1, w: 1, h: 1}} />;
});
}, [props.count]);
return <ReactGridLayout cols={12}>{children}</ReactGridLayout>;
}
Because the children prop doesn't change between rerenders, updates to <MyGrid> won't result in new renders, improving performance.
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.
data-grid key)0.18.2 (Feb 26, 2020)
shouldComponentUpdate:
shouldComponentUpdate was shipped in 0.18.0-0.18.1 (#1123), which did not compare the children object. While this works well in many simple implementations of RGL, it breaks in more complex applications.props.children and nextProps.children is now added to <ReactGridLayout> and <GridItem>. If you wish to take advantage of the performance improvements from the shouldComponentUpdate work, memoize your children.FAQs
A draggable and resizable grid layout with responsive breakpoints, for React.
The npm package react-grid-layout receives a total of 386,863 weekly downloads. As such, react-grid-layout popularity was classified as popular.
We found that react-grid-layout demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.