React-Draggable

React draggable component

ReactDrag and drop
react-grid-layout/react-draggablereact-draggable

README

React-Draggable

TravisCI Build Status Appveyor Build Status npm downloads [gzip size]() [version]()


A simple component for making elements draggable.

  1. ``` js
  2. <Draggable>
  3.   <div>I can now be moved around!</div>
  4. </Draggable>
  5. ```

- Demo
- Changelog


|VersionCompatibility|
|------------|--------------|
|4.xReact
|3.xReact
|2.xReact
|1.xReact
|0.xReact


Technical Documentation


- Installing
- Exports
- Draggable
- Draggable Usage
- Draggable API
- Controlled vs. Uncontrolled
- DraggableCore
- DraggableCore API



Installing


  1. ``` sh
  2. $ npm install react-draggable
  3. ```

If you aren't using browserify/webpack, a
UMD version of react-draggable is available. It is updated per-release only.
This bundle is also what is loaded when installing from npm. It expects external React and ReactDOM.

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.

Exports


The default export is ``. At the `.DraggableCore` property is [``](#draggablecore).
Here's how to use it:

  1. ``` js
  2. // ES6
  3. import Draggable from 'react-draggable'; // The default
  4. import {DraggableCore} from 'react-draggable'; //
  5. import Draggable, {DraggableCore} from 'react-draggable'; // Both at the same time

  7. // CommonJS
  8. let Draggable = require('react-draggable');
  9. let DraggableCore = Draggable.DraggableCore;
  10. ```

## ``

A `` 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 ``. Usean intermediate wrapper (`...`) in this case.

Draggable Usage


View the Demo and its
source for more.

  1. ``` js
  2. import React from 'react';
  3. import ReactDOM from 'react-dom';
  4. import Draggable from 'react-draggable';

  6. class App extends React.Component {

  8.   eventLogger = (e: MouseEvent, data: Object) => {
  9.     console.log('Event: ', e);
  10.     console.log('Data: ', data);
  11.   };

  13.   render() {
  14.     return (
  15.       <Draggable
  16.         axis="x"
  17.         handle=".handle"
  18.         defaultPosition={{x: 0, y: 0}}
  19.         position={null}
  20.         grid={[25, 25]}
  21.         scale={1}
  22.         onStart={this.handleStart}
  23.         onDrag={this.handleDrag}
  24.         onStop={this.handleStop}>
  25.         <div>
  26.           <div className="handle">Drag from here</div>
  27.           <div>This readme is really dragging on...</div>
  28.         </div>
  29.       </Draggable>
  30.     );
  31.   }
  32. }

  34. ReactDOM.render(<App/>, document.body);
  35. ```

Draggable API


The `` component transparently adds draggability to its children.

Note: Only a single child is allowed or an Error will be thrown.

For the `` component to correctly attach itself to its child, the child element must provide support
for the following props:
- style is used to give the transform css to the child.
- className is used to apply the proper classes to the object being dragged.
- onMouseDown, onMouseUp, onTouchStart, and onTouchEnd  are used to keep track of dragging state.

React.DOM elements support the above properties by default, so you may use those elements as children without
any changes. If you wish to use a React component you created, you'll need to be sure to
transfer prop.

#### `` Props:

  1. ``` js
  2. //
  3. // Types:
  4. //
  5. type DraggableEventHandler = (e: Event, data: DraggableData) => void | false;
  6. type DraggableData = {
  7.   node: HTMLElement,
  8.   // lastX + deltaX === x
  9.   x: number, y: number,
  10.   deltaX: number, deltaY: number,
  11.   lastX: number, lastY: number
  12. };

  14. //
  15. // Props:
  16. //
  17. {
  18. // If set to `true`, will allow dragging on non left-button clicks.
  19. allowAnyClick: boolean,

  21. // Determines which axis the draggable can move. This only affects
  22. // flushing to the DOM. Callbacks will still include all values.
  23. // Accepted values:
  24. // - `both` allows movement horizontally and vertically (default).
  25. // - `x` limits movement to horizontal axis.
  26. // - `y` limits movement to vertical axis.
  27. // - 'none' stops all movement.
  28. axis: string,

  30. // Specifies movement boundaries. Accepted values:
  31. // - `parent` restricts movement within the node's offsetParent
  32. //    (nearest node with position relative or absolute), or
  33. // - a selector, restricts movement within the targeted node
  34. // - An object with `left, top, right, and bottom` properties.
  35. //   These indicate how far in each direction the draggable
  36. //   can be moved.
  37. bounds: {left?: number, top?: number, right?: number, bottom?: number} | string,

  39. // Specifies a selector to be used to prevent drag initialization. The string is passed to
  40. // Element.matches, so it's possible to use multiple selectors like `.first, .second`.
  41. // Example: '.body'
  42. cancel: string,

  44. // Class names for draggable UI.
  45. // Default to 'react-draggable', 'react-draggable-dragging', and 'react-draggable-dragged'
  46. defaultClassName: string,
  47. defaultClassNameDragging: string,
  48. defaultClassNameDragged: string,

  50. // Specifies the `x` and `y` that the dragged item should start at.
  51. // This is generally not necessary to use (you can use absolute or relative
  52. // positioning of the child directly), but can be helpful for uniformity in
  53. // your callbacks and with css transforms.
  54. defaultPosition: {x: number, y: number},

  56. // If true, will not call any drag handlers.
  57. disabled: boolean,

  59. // Specifies the x and y that dragging should snap to.
  60. grid: [number, number],

  62. // Specifies a selector to be used as the handle that initiates drag.
  63. // Example: '.handle'
  64. handle: string,

  66. // If desired, you can provide your own offsetParent for drag calculations.
  67. // By default, we use the Draggable's offsetParent. This can be useful for elements
  68. // with odd display types or floats.
  69. offsetParent: HTMLElement,

  71. // Called whenever the user mouses down. Called regardless of handle or
  72. // disabled status.
  73. onMouseDown: (e: MouseEvent) => void,

  75. // Called when dragging starts. If `false` is returned any handler,
  76. // the action will cancel.
  77. onStart: DraggableEventHandler,

  79. // Called while dragging.
  80. onDrag: DraggableEventHandler,

  82. // Called when dragging stops.
  83. onStop: DraggableEventHandler,

  85. // If running in React Strict mode, ReactDOM.findDOMNode() is deprecated.
  86. // Unfortunately, in order for to work properly, we need raw access
  87. // to the underlying DOM node. If you want to avoid the warning, pass a `nodeRef`
  88. // as in this example:
  89. //
  90. // function MyComponent() {
  91. //   const nodeRef = React.useRef(null);
  92. //   return (
  93. //    
  94. //      
    Example Target
  95. //    
  96. //   );
  97. // }
  98. //
  99. // This can be used for arbitrarily nested components, so long as the ref ends up
  100. // pointing to the actual child DOM node and not a custom component.
  101. //
  102. // For rich components, you need to both forward the ref *and props* to the underlying DOM
  103. // element. Props must be forwarded so that DOM event handlers can be attached.
  104. // For example:
  105. //
  106. //   const Component1 = React.forwardRef(function (props, ref) {
  107. //     return
    Nested component
    ;
  108. //   });
  109. //
  110. //   const nodeRef = React.useRef(null);
  111. //  
  112. //    
  113. //  
  114. //
  115. // Thanks to react-transition-group for the inspiration.
  116. //
  117. // `nodeRef` is also available on .
  118. nodeRef: React.Ref<typeof React.Component>,

  120. // Much like React form elements, if this property is present, the item
  121. // becomes 'controlled' and is not responsive to user input. Use `position`
  122. // if you need to have direct control of the element.
  123. position: {x: number, y: number}

  125. // A position offset to start with. Useful for giving an initial position
  126. // to the element. Differs from `defaultPosition` in that it does not
  127. // affect the position returned in draggable callbacks, and in that it
  128. // accepts strings, like `{x: '10%', y: '10%'}`.
  129. positionOffset: {x: number | string, y: number | string},

  131. // Specifies the scale of the canvas your are dragging this element on. This allows
  132. // you to, for example, get the correct drag deltas while you are zoomed in or out via
  133. // a transform or matrix in the parent of this element.
  134. scale: number
  135. }
  136. ```


Note that sending className, style, or transform as properties will error - set them on the child element
directly.


Controlled vs. Uncontrolled


`` is a 'batteries-included' component that manages its own state. If you want to completelycontrol the lifecycle of the component, use ``.

For some users, they may want the nice state management that `` provides, but occasionally wantto programmatically reposition their components. `` allows this customization via a system that
is similar to how React handles form components.

If the prop `position: {x: number, y: number}` is defined, the `` will ignore its internal state and use
the provided position instead. Alternatively, you can seed the position using defaultPosition. Technically, since
`` works only on position deltas, you could also seed the initial position using CSS `top/left`.

We make one modification to the React philosophy here - we still allow dragging while a component is controlled.
We then expect you to use at least an onDrag or onStop handler to synchronize state.

To disable dragging while controlled, send the prop `disabled={true}` - at this point the `` will operate
like a completely static component.

## ``

For users that require absolute control, a `` element is available. This is useful as an abstractionover touch and mouse events, but with full control. `` has no internal state.

See React-Resizable and
React-Grid-Layout for some usage examples.

`` is a useful building block for other libraries that simply want to abstract browser-specific
quirks and receive callbacks when a user attempts to move an element. It does not set styles or transforms
on itself and thus must have callbacks attached to be useful.

DraggableCore API


`` takes a limited subset of options:

  1. ``` js
  2. {
  3.   allowAnyClick: boolean,
  4.   cancel: string,
  5.   disabled: boolean,
  6.   enableUserSelectHack: boolean,
  7.   offsetParent: HTMLElement,
  8.   grid: [number, number],
  9.   handle: string,
  10.   onStart: DraggableEventHandler,
  11.   onDrag: DraggableEventHandler,
  12.   onStop: DraggableEventHandler,
  13.   onMouseDown: (e: MouseEvent) => void,
  14.   scale: number
  15. }
  16. ```

Note that there is no start position. `` simply calls `drag` handlers with the below parameters,
indicating its position (as inferred from the underlying MouseEvent) and deltas. It is up to the parent
to set actual positions on ``.

Drag callbacks (`onStart`, `onDrag`, `onStop`) are called with the [same arguments as ``](#draggable-api).


Contributing


- Fork the project
- Run the project in development mode: $ npm run dev
- Make changes.
- Add appropriate tests
- $ npm 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