Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

jx-3-react

STRML4MIT0.13.13

A draggable and resizable grid layout with responsive breakpoints, for React. Customized fork.

react, grid, drag, draggable, resize, resizable, fluid, responsive

readme

React-Grid-Layout

Customized fork.

travis build npm package npm downloads

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.

BitMEX UI

GIF from production usage on BitMEX.com

[Demo | Changelog | WebpackBin Editable demo]

Table of Contents

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

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
Version Compatibility
>= 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
var ReactGridLayout = require('react-grid-layout');

var MyFirstGrid = React.createClass({
  render: function() {
    // layout is an array of objects, see the demo for more complete usage
    var 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 (
      <ReactGridLayout 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>
      </ReactGridLayout>
    )
  }
});

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

var ReactGridLayout = require('react-grid-layout');

var MyFirstGrid = React.createClass({
  render: function () {
    return (
      <ReactGridLayout 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>
      </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.

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.

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.

import {Responsive, WidthProvider} from 'react-grid-layout';
const ResponsiveReactGridLayout = WidthProvider(Responsive);

//...
render() {
  // {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.

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.

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 <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 = '',

// DEPRECATED If true, the layout will compact vertically
// verticalCompact: ?boolean = true,

// Compaction type. Can be: 'vertical', 'horizontal'.
compactType: ?string = 'vertical',

// Enable/disable compact while resize item.
compactOnResize: ?bool = true,

// Delegates compact method. It should return the compacted layout. Options has activeDrag item in drag events.
// Method called when onDrag, onDragStop, onResize, onResizeStop.
customCompact: (layout: Layout, compactType: CompactType, cols: number, options: object) => compactLayout: Layout,

// Minimun proportion to change size.
resizeProportion: ?number = 0.5,

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

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

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

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: ?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},

// layouts is an object mapping breakpoints to layouts.
// e.g. {lg: Layout, md: Layout, ...}
layouts: {[key: $Keys<breakpoints>]: Layout}

//
// Ref
//
// Ref for React Grid in Responsivbe Grid Layout.
reactGridRef: (reactGrid : ReactGrid) => void,

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

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

{

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

  // A CSS selector for tags that will act as the draggable handle of this item.
  // It overrides the draggableHandle.
  handle: ?string
}

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 WebpackBin to help us easily isolate it.

TODO List

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

changelog

Changelog

0.13.10 (Unreleased)

Features:

  • New test suite - thanks @nikolas
  • Dev Dependency updates
  • Committed yarn.lock

0.13.9 (Oct 13, 2016)

Fixes:

  • Fixed sorting of layout items, which could be different in IE if two items have the same x & y coordinate.

0.13.8 (Oct 13, 2016)

Fixes:

  • Fixed breakage introduced in 0.13.7 when items are added without a layout or data-grid property.

0.13.7 (Oct 3, 2016)

Fixes:

  • Fixed an error during layout sync if children was a keyed fragment or had nested arrays.
  • Fixed onLayoutChange being called when layout didn't change.
  • Fixed some issues with input layout items being modified in-place rather than cloned.
  • Minor typos.

0.13.6 (Sep 26, 2016)

Fixes:

  • Fixed missing HTMLElement in onResize* callbacks.

0.13.5 (Sep 9, 2016)

Fixes:

  • Fixed a few Flow typing errors in WidthProvider.

0.13.4 (Sep 9, 2016)

Fixes:

  • Fixed potential call to ReactDOM.findDOMNode(this) after unmount of WidthProvider.
  • Fixed an issue where layout items using data-grid could rearrange on mount depending on how they were ordered.
    • See #342 for reference.

0.13.3 (Aug 31, 2016)

Fixes:

  • Fixed lodash.isequal import, which was ruined by case-insensitive HFS+ shakes fist

0.13.2 (Aug 31, 2016)

Fixes:

  • Diffing children in order to regenerate the layout now diffs the key props and their order.
    • This will catch more changes, such as sorting, addition, and removal.
  • Only pass className and style to WidthProvider. Other props were not intended to be supported.
    • I'm aware this could be a breaking change if you were relying on this bad behavior. If so, please use your own WidthProvider-style HOC.
  • babel-plugin-transform-flow-comments had limited support for defining types like transpiled classes.
    • This has been updated to instead copy source to .js.flow files, which preserves all type information.

0.13.1 (Aug 16, 2016)

Fixes:

  • Fix remaining propTypes warnings.

0.13.0 (Aug 3, 2016)

Changed:

  • Due to a change in React 15.2, passing the _grid property on DOM children generates an error. To compensate, we now error on the same and suggest using data-grid instead. Simply change any use of _grid to data-grid, or add your properties to the layout.

Fixes:

  • Fix React 15.3 warning re: propTypes.

0.12.7 (Jun 29, 2016)

  • Prevent extraenous rerenders in <ResponsiveReactGridLayout> by using deep equality on layouts.

0.12.6 (Jun 5, 2016)

  • Fix blindingly obvious bug where mounted isn't set to true. Smack forehead.

0.12.5 (Jun 3, 2016)

  • Fixes for server rendering checksum failures.

0.12.4 (May 22, 2016)

  • Update to React-Draggable v2. Fixes: #241, #239, #24
    • v2 contains a number of bugfixes & enhancements for touchscreens, multitouch, and scrolling containers.

0.12.3 (May 3, 2016)

  • Bugfix: Rendering with new breakpoints/cols does not refresh the layout. Fixes #208 - thanks @damienleroux

0.12.2 (May 1, 2016)

  • Bugfix: Fix warning about undefined useCSSTransforms when server-rendering.

0.12.1 (Apr 19, 2016)

  • Bugfix: Don't set layout twice on width change. See #217 - thanks @damienleroux
  • Enhancement: Add Flow type comments

0.12.0 (Apr 14, 2016)

  • <ReactGridLayout> will no longer animate so severely on mount. See #212.
    • If you are using <WidthProvider>, you may notice that the container's width still shunts on mount. If you like, you may delay mounting by setting measureBeforeMount={true} on the wrapped element. This will eliminate the mounting animation completely.
    • If you enjoyed the old animation, set useCSSTransforms={this.state.mounted} and toggle the mounting flag. See 0-showcase.jsx for an example.
  • Set more permissive version ranges for <Draggable> and <Resizable> dependencies, as they are now stable and will only introduce breaking changes on major version ticks.

0.11.3 (Apr 8, 2016)

  • Officially support React v15.

0.11.2 (Apr 6, 2016)

  • Bugfix: Draggable cancel selectors, see #203 - thanks @RiiD
  • README fixes, thanks @bravo-kernel & @ro-savage

0.11.1

  • Bugfix: <ResponsiveReactGridLayout> was using stale data when synchronizing children with the layout on a breakpoint change.

0.11.0

This release contains potentially breaking changes so I have updated the minor version (as per semver).

Breaking Changes:

  • Layout items now have a fixed set of properties. Other properties will not be merged into the <GridItem>, such as className. To set a className on a child, set it on the child directly and it will be merged. This allows us to make better assumptions about the layout and use a faster cloning mechanism.
  • Setting individual handle and cancel selectors per item is no longer supported. If you need this, please open a ticket and let me know your use case.

Other changes:

  • Bugfix: <ResponsiveReactGridLayout> onLayoutChange callback data could still be stale.
  • Bugfix: Range error when building layout solely from _grid properties.
    • This broke a lot of usage and thus 0.10.11 and 0.10.10 have been unpublished.
  • Removed redundant isPlaceholder property from <GridItem>.
  • README updates to clarify layout/_grid usage.

0.10.11

  • Bugfix: layouts param on <ResponsiveReactGridLayout>'s onLayoutChange could have stale data for the current breakpoint.

0.10.10

  • Performance: Prevent V8 deopt in a few methods and add fast layout item cloning.

0.10.9

  • Bugfix: Typo in children comparison in CWRP. See #169.
  • Bugfix: Missing babel-preset-es2015 in dev.

0.10.8

0.10.7

  • Bugfix: className and style props on grid children were being incorrectly dropped, a holdover from when cloneWithProps() used to do this merging for us. They are now merged.

0.10.6

  • Bugfix: If both props.layout and props.children.length change in the same tick, props.layout would be clobbered. See #162

0.10.5

  • Bugfix/Enhancement: Margins were causing subtle error in some of the positioning calculations. This has been fixed.

0.10.4

  • Bugfix: Container height was calculated as less than expected due to improper addition of margin.

0.10.3

  • Bugfix: Round item positions even if they're currently resizing or dragging (#158, regression of #141)
  • Bugfix: Fix a positioning bug when margins are 0 (#160)

0.10.2

  • Bugfix: <RGL> would synchronize children with layout if the layout in props didn't match the state; this was meant to be a hook for the developer to supply a new layout. The incorrect check could cause the layout to reset if the parent rerendered. The check is now between the layout in nextProps and props.
  • Bugfix: Fixed a lot of resizing layout bugs; most of the fixes are in react-resizable.
  • Bugfix: Fixed incorrect typecheck on LayoutItem.i.
  • Bugfix: Make onLayoutChange fire appropriately (#155).
  • Bugfix: Fix <ResponsiveGridLayout> not properly reverting when sizing the page up (#154).
  • Remove unused offsetX and offsetY from layouts.
  • Dependency updates.

0.10.1

  • Hotfix for default export incompatibility caused by Babel 6.

0.10.0

This long-awaited release provides React 0.14 compatibility and a rewrite of the underlying <Draggable> functionality.

Breaking changes:

  • ListensToWidth replaced with WidthProvider which must wrap <ResponsiveReactGridLayout> and <ReactGridLayout> to provide width data. See doc for example.
  • Prop initialWidth renamed to width.
  • Grid Layout keys must be type of string now.

Other changes:

  • Finally compatible with React 0.14! Big thanks to @menelike for his help.
  • Upgraded to Babel 6.
  • Full typechecking via Flow.
  • Lots of misc bugfixes.
    • See beta releases below for more details.

0.10.0-beta1

  • Fixed a React import bug on ListensToWidth.jsx (#130; thanks @mrblueblue)

0.10.0-beta0

This release is unstable!

  • React 0.14 compatibility.
  • This release includes a rewrite of much of the project in ES6/7 style with Flow typing.
  • This release brings us onto mainline (1.x) react-draggable and react-resizable, eliminating the previous github dependency.
  • 0.10.0 is not yet complete. Use this release at your own risk.

Known bugs:

  • The placeholder box does not properly follow the mouse and stays pinned to the active drag.

0.9.2

  • Update react-draggable to v0.8.0 to fix IE11 issues (#29).

0.9.1

  • Update react-draggable to v0.7.3 to fix a bounds bug (#56).

0.9.0

  • Move off react-draggable fork to mainline v0.7.2. Incremented minor (major in the case of npm's ^, since we are pre-v1) version in case of unforeseen conflicts.

0.8.3

  • Add verticalCompact toggle.

0.8.2

  • Fix a crash when initializing with no children.

0.8.1

  • Fixed React 0.13 warning about isMounted().
  • Update to babel 5.
  • Added browser build for use with a <script> tag or in RequireJS builds.
  • Pinned react-draggable version in anticipation of React 0.13 update.

0.8.0

  • Changed signature on resize/drag callbacks to allow dynamic max/min W/H per item.
  • Fixed bug in useCSSTransforms.
  • Documentation and example fixes.

0.7.1

  • Added callbacks for resize and drag start/active/stop.

0.7.0

Breaking changes:

  • ReactGridLayout.props.handle renamed to ReactGridLayout.props.draggableHandle.

This version contains a CSS update. This fixes a visual bug where you may see items quickly reset position and animate back to their original position on load, when you are using CSS transforms. To fix this bug, copy the rules from css/styles.css into your stylesheet.

Other changes:

  • Fixed #19 (bad new item placement with css transforms).
  • Fixed some placement inconsistencies while RGL is mounting, with css transforms and percentages.
  • Fixed a duplicate className bug.

0.6.2

  • Fix #21 (error when passing only a single child).
  • Add GridItem.props.cancel.
  • Use React addons directly to save file size.
  • Allow setting draggable/resizable per grid item, as well as existing static property.
  • Use object.assign to set _grid properties so we can more easily merge PRs in the future.

0.6.1

  • Fixed #8 (current layout was not properly being stored when provided via _grid props).

0.6.0

  • Optionally use CSS transforms for placement, fallback on position top/left.
  • Allow parent to set responsive breakpoint directly.

0.5.2

  • Fix Responsive import for node users

0.5.1

  • Add support for min/max dimension attributes.
  • Example tweak

0.5.0

  • Refactoring and demo tweaks. Update README with new params.
  • Add showcase example, tweak template
  • Refactor: Responsive Grid Layout is a separate element
  • Auto-generate examples from template rather than edit them individually.

0.4.0

  • Force lodash into commons chunk
  • More tweaks to grid collisions. This should fix bad swaps once and for all.
  • Set unused:"vars" in lint.
  • Add responsive localstorage example and initialLayouts support.
  • Fix localstorage example comment.
  • Rework responsive layouts, identify child elements by key rather than index. Added 2 new examples.
  • Fixup GridItem resizing feel a bit.

< 0.4.0

  • Early development versions, too many changes to list.