react-draggable

What is react-draggable?

The react-draggable npm package allows React components to be draggable within the DOM. It provides a simple way to make elements draggable and offers various customization options such as grid snapping, axis locking, and event handling for drag actions.

What are react-draggable's main functionalities?

Basic Dragging

This code snippet enables basic dragging functionality for the enclosed <div> element.

{"<Draggable><div>I can be dragged</div></Draggable>"}

Controlled Draggable

This example shows a controlled component where the position is managed by the component's state, allowing for more complex interactions.

{"<Draggable position={this.state.position} onDrag={this.handleDrag}><div>I can be dragged</div></Draggable>"}

Axis Constraints

This code restricts the dragging movement to the horizontal axis.

{"<Draggable axis='x'><div>I can only be dragged horizontally</div></Draggable>"}

Grid Snapping

This snippet makes the element snap to a grid pattern as it's being dragged.

{"<Draggable grid={[25, 25]}><div>I snap to a 25x25 grid</div></Draggable>"}

Bounds Limitation

This code ensures that the draggable element cannot be moved outside the bounds of its parent container.

{"<Draggable bounds='parent'><div>I can't be dragged outside my parent</div></Draggable>"}

Other packages similar to react-draggable

react-beautiful-dnd

This package provides a higher level of abstraction for creating draggable and droppable interfaces, focusing on vertical and horizontal lists. It's more suitable for complex drag-and-drop interfaces, compared to react-draggable which is more low-level.

react-dnd

React DnD is a set of React utilities to help you build complex drag and drop interfaces while keeping your components decoupled. It is more comprehensive than react-draggable and uses the HTML5 drag and drop API.

react-sortable-hoc

This package provides components and higher-order components to make elements sortable via drag-and-drop. It's specifically designed for creating sortable lists and grids, unlike react-draggable which is for general-purpose dragging.

react-grid-layout

React Grid Layout is a grid layout system much like Packery or Gridster, for React. It allows users to create draggable and resizable layouts. It's more specialized for layout management compared to react-draggable which is for dragging elements.

README

react-draggable

A simple component for making elements draggable.

View the Changelog

Demo

View Demo

Installing

$ npm install react-draggable

If you aren't using browserify/webpack, a UMD version of react-draggable is available. It is updated per-release only.

If you want a UMD version of the latest master revision, you can generate it yourself from master by cloning this repository and running $ make. This will create umd dist files in the dist/ folder.

Details

A <Draggable> element wraps an existing element and extends it with new event handlers and styles. It does not create a wrapper element in the DOM.

Draggable items are moved using CSS Transforms. This allows items to be dragged regardless of their current positioning (relative, absolute, or static). Elements can also be moved between drags without incident.

If the item you are dragging already has a CSS Transform applied, it will be overwritten by <Draggable>. Use an intermediate wrapper (<Draggable><span>...</span></Draggable>) in this case.

Example

/** @jsx React.DOM */
var React = require('react'),
	Draggable = require('react-draggable');

var App = React.createClass({
	handleStart: function (event, ui) {
		console.log('Event: ', event);
		console.log('Position: ', ui.position);
	},

	handleDrag: function (event, ui) {
		console.log('Event: ', event);
        console.log('Position: ', ui.position);
	},

	handleStop: function (event, ui) {
		console.log('Event: ', event);
        console.log('Position: ', ui.position);
	},

	render: function () {
		return (
			// <Draggable/> transparently adds draggable interactivity
			// to whatever element is supplied as `this.props.children`.
			// Only a single element is allowed or an Error will be thrown.
			//
			// The element is moved from its current position using absolute positioning.
			//
			// `axis` determines which axis the draggable can move.
			// - 'both' allows movement horizontally and vertically (default).
			// - 'x' limits movement to horizontal axis.
			// - 'y' limits movement to vertical axis.
			//
			// `handle` specifies a selector to be used as the handle that initiates drag.
			//
			// `cancel` specifies a selector to be used to prevent drag initialization.
			//
			// `grid` specifies the x and y that dragging should snap to.
			//
			// `bounds` specifies movement boundaries. Pass:
			// - 'parent' restricts movement within the node's offsetParent
			//	 (nearest node with position relative or absolute), or
			// - An object with left, top, right, and bottom properties.
			//
			// `zIndex` specifies the zIndex to use while dragging.
			//
			// `onStart` is called when dragging starts.
			//
			// `onDrag` is called while dragging.
			//
			// `onStop` is called when dragging stops.

			<Draggable
				axis="x"
				handle=".handle"
				grid={[25, 25]}
				zIndex={100}
				onStart={this.handleStart}
				onDrag={this.handleDrag}
				onStop={this.handleStop}>
				<div>
					<div className="handle">Drag from here</div>
					<div>Lorem ipsum...</div>
				</div>
			</Draggable>
		);
	}
});

React.renderComponent(<App/>, document.body);

Contributing

• Fork the project
• Run the project in development mode: $ make dev
• Make changes.
• Add appropriate tests
• $ make test
• If tests don't pass, make them pass.
• Update README with appropriate docs.
• Commit and PR

Release checklist

• Update CHANGELOG
• make release-patch, make release-minor, or make-release-major
• make publish

License

MIT