This library will help you make your elements draggable inside React.
npm install @martdev/react-drag
or yarn
yarn add @martdev/react-drag
draggableProps = {
as?: keyof JSX.IntrinsicElements = 'div',
disabled?: boolean = false,
onDragStart?: (coords, nativeEvent) => boolean | void,
onDrag?: (coords, nativeEvent) => boolean | newCoods | void,
onDragEnd?: (coords, nativeEvent) => void,
}
targetProps = {
as?: keyof JSX.IntrinsicElements = 'div',
}
notTargetProps = {
as?: keyof JSX.IntrinsicElements = 'div',
}
<Draggable {...draggableProps}>
<Target {...targetProps}>
...
</Target>
<NotTarget {...notTargetProps}>
...
</NotTarget>
</Draggable>
{ isDragging: boolean } = useDrag({
containerRef: RefObject<HTMLElement>,
targetRefList?: [RefObject<HTMLElement>, ...] = [],
notTargetRefList?: [RefObject<HTMLElement>, ...] = [],
disabled?: boolean = false,
onDragStart?: (coords, nativeEvent) => boolean | void,
onDrag?: (coords, nativeEvent) => boolean | newCoods | void,
onDragEnd?: (coords, nativeEvent) => void,
})
It is a container component that will be «draggable».
Extends: HTMLAttributes<HTMLElement>
, and it means it is capable to transmit any basic properties of HTML-elements (for example, className
, role
, onClick
, title
, etc.).
The list of props is below:
Optional prop that sets an element type (div
, span
, img
, etc.).
Default value: "div"
Optional prop needed for enabling/disabling the element to be «draggable».
Use this prop if you need to disable the element to be «draggable» for some conditions.
Default value: false
Optional function that is an event handler and is called out before the start of «dragging».
It receives following arguments:
coords
— an array of two numeric values (x
,y
), and those contain information about the element's current position (in the moment of event's call).nativeEvent
— a native event's object that is initialized after completion ofMouseEvent
orTouchEvent
(depending on device's type). It should be used with caution. If you need to getMouseEvent
's props, you better specify conditionnativeEvent.type.startsWith('mouse')
.
Return value variants:
void
— the event will be executed with default values.false
— use this if you need to abort the element's «dragging».
Optional function that is an event handler and is called out in every change of element's position during its «dragging».
It receives following arguments:
coords
— an array of two numeric values (x
,y
), and those contain information about the element's current position (in the moment of event's call).nativeEvent
— a native event's object that is initialized after completion ofMouseEvent
orTouchEvent
(depending on device's type). It should be used with caution. If you need to getMouseEvent
's props, you better specify conditionnativeEvent.type.startsWith('mouse')
.
Return value variants:
void
— the event will be executed with default values.false
— use this if you need to abort the element's «dragging».newCoords
— an array of two numeric values (x
,y
), and those contain new values for element's position.
Optional function that is an event handler and is called out after completion of element's «dragging».
It receives following arguments:
coords
— an array of two numeric values (x
,y
), and those contain information about the element's current position (in the moment of event's call).nativeEvent
— a native event's object that is initialized after completion ofMouseEvent
orTouchEvent
(depending on device's type). It should be used with caution. If you need to getMouseEvent
's props, you better specify conditionnativeEvent.type.startsWith('mouse')
.
Return value variants:
void
— the event will be executed with default values.- there are no more value options available
A component that is a target area for «dragging» the container.
If this component does not exist, then «the target» is the container itself.
Use this component only inside <Draggable>
, or else the error will happen.
Extends: HTMLAttributes<HTMLElement>
, and it means it is capable to transmit any basic props of HTML-elements (for example, className
, role
, onClick
, title
, etc.).
The list of props is below:
Optional prop that sets an element type (div
, span
, img
, etc.).
Default value: "div"
This component is the exact opposite of <Target>
component.
The main goal of this component is to give opportunity to ignore the container «dragging» if this action is used on specific/concrete element.
Use this component only inside <Draggable>
or <Target>
, or else the error will happen.
Extends: HTMLAttributes<HTMLElement>
, and it means it is capable to transmit any basic props of HTML-elements (for example, className
, role
, onClick
, title
, etc.).
The list of props is below:
Optional prop that sets an element type (div
, span
, img
, etc.).
Default value: "div"
This hook will give you opportunity to use the element's «dragging» without usage of integral components.
Use this hook if you want to interact with elements directly and if there is not enough functionality for integral components usage.
An object with a list of props, which are stated below:
Required prop, which value is a ref
on container element that will be «draggable».
This value must be created with React hook useRef
with reference on HTMLElement
.
Optional prop — an array of ref
references on elements which will be a target area for «dragging» the container.
This prop is an analogue of <Target>
component.
Values of this prop must be created React's hook useRef
with reference on HTMLElement
.
Optional prop — an array of ref
references on elements which will ignore «dragging» the container.
This prop is the opposite of targetRefList
prop and is an analogue of <NotTarget>
component
The main goal of this component is to give opportunity to ignore the container «dragging» if this action is used on specific/concrete element.
Values of this prop must be created with React hook useRef
with reference on HTMLElement
.
Optional prop needed for enabling/disabling the element to be «draggable».
Use this prop if you need to disable the element to be «draggable» for some conditions.
Default value: false
Optional function that is an event handler and is called out before the start of «dragging».
It receives following arguments:
coords
— an array of two numeric values (x
,y
), and those contain information about the element's current position (in the moment of event's call).nativeEvent
— a native event's object that is initialized after completion ofMouseEvent
orTouchEvent
(depending on device's type). It should be used with caution. If you need to getMouseEvent
's props, you better specify conditionnativeEvent.type.startsWith('mouse')
.
Return value variants:
void
— the event will be executed with default values.false
— use this if you need to abort the element's «dragging».
Optional function that is an event handler and is called out in every change of element's position during its «dragging».
It receives following arguments:
coords
— an array of two numeric values (x
,y
), and those contain information about the element's current position (in the moment of event's call).nativeEvent
— a native event's object that is initialized after completion ofMouseEvent
orTouchEvent
(depending on device's type). It should be used with caution. If you need to getMouseEvent
's props, you better specify conditionnativeEvent.type.startsWith('mouse')
.
Return value variant:
void
— the event will be executed with default values.false
— use this if you need to abort the element's «dragging».newCoords
— an array of two numeric values (x
,y
), and those contain new values for element's position.
Optional function that is an event handler and is called out after completion of element's «dragging».
It receives following arguments:
coords
— an array of two numeric values (x
,y
), and those contain information about the element's current position (in the moment of event's call).nativeEvent
— a native event's object that is initialized after completion ofMouseEvent
orTouchEvent
(depending on device's type). It should be used with caution. If you need to getMouseEvent
's props, you better specify an conditionnativeEvent.type.startsWith('mouse')
.
Return value variants/options:
void
— the event will be executed with default values.- there are no more value options available
A classic example without using <Target>
and <NotTarget>
.
There will be a small blue square that you can «drag» across the whole page.
.box {
background-color: #a9def9;
height: 100px;
position: absolute;
width: 100px;
}
const App = () => {
return (
<Draggable className="box" />
);
};
Example with using disabled
prop.
In 10 seconds after the square is displayed, «dragging» will be disabled.
.box {
background-color: #a9def9;
height: 100px;
position: absolute;
width: 100px;
}
const App = () => {
const [disabled, setDisabled] = useState(false);
useEffect(() => {
window.setTimeout(() => {
setDisabled(true);
}, 10000);
}, []);
return (
<Draggable className="box" disabled={disabled} />
);
};
Usage <Target>
as the target element of «dragging».
In this example, «dragging» is possible only outside the «pink area».
.box {
background-color: #a9def9;
height: 100px;
position: absolute;
width: 100px;
}
.target {
background-color: #e4c1f9;
height: 30px;
}
const App = () => {
return (
<Draggable className="box">
<Target className="target" />
</Draggable>
);
};
Using three <Target>
as the target element of «dragging».
In this example, «dragging» is possible only outside the «pink area».
.box {
background-color: #a9def9;
display: flex;
flex-direction: column;
height: 100px;
justify-content: space-between;
position: absolute;
width: 100px;
}
.target {
background-color: #e4c1f9;
height: 20px;
}
const App = () => {
return (
<Draggable className="box">
<Target className="target" />
<Target className="target" />
<Target className="target" />
</Draggable>
);
};
Using <Target>
as a text that will be the target of «dragging».
In this example, «dragging» is possible only after the word «world».
.text {
color: #333333;
font-size: 24px;
font-weight: bold;
position: absolute;
white-space: nowrap;
}
const App = () => {
return (
<Draggable className="text">
Hello <Target as="span">world</Target>!
</Draggable>
);
};
Using <NotTarget>
for ignoring the «dragging».
In this example, «dragging» outside the «green area» is impossible.
.box {
background-color: #a9def9;
height: 100px;
position: fixed;
width: 100px;
}
.target {
background-color: #e4c1f9;
height: 30px;
}
.not-target {
background-color: #d0f4de;
height: 30px;
margin-left: auto;
width: 30px;
}
const App = () => {
return (
<Draggable className="box">
<Target className="target">
<NotTarget className="not-target" />
</Target>
</Draggable>
);
};
Use an event handler onDrag
to limit «dragging» on the area.
In this example, «dragging» is possible only within the browser's window.
.box {
background-color: #a9def9;
height: 100px;
position: fixed;
width: 100px;
}
.target {
background-color: #e4c1f9;
height: 30px;
}
const App = () => {
const handleDrag = (coords) => {
const [currentX, currentY] = coords;
const newX = Math.max(0, Math.min(window.innerWidth - 100, currentX));
const newY = Math.max(0, Math.min(window.innerHeight - 100, currentY));
return [newX, newY];
};
return (
<Draggable className="box" onDrag={handleDrag}>
<Target className="target" />
</Draggable>
);
};
Use event handlers onDragStart
and onDragEnd
for determine status.
In this example, by «dragging» the element will change its color because of adding/deleting additional CSS-class.
.box {
background-color: #a9def9;
height: 100px;
position: absolute;
transition: background-color 0.3s ease-in;
width: 100px;
}
.box-dragging {
background-color: #e4c1f9;
}
const App = () => {
const [dragging, setDragging] = useState(false);
const handleDragStart = () => {
setDragging(true);
};
const handleDragEnd = () => {
setDragging(false);
};
return (
<Draggable
className={!dragging ? 'box' : 'box box-dragging'}
onDragStart={handleDragStart}
onDragEnd={handleDragEnd}
/>
);
};
Using useDrag
hook to give the user possibility to «drag» the element.
In this example, «dragging» is possible only outside the «pink area».
If the status changes, its value is displayed in console.
.box {
background-color: #a9def9;
height: 100px;
position: absolute;
width: 100px;
}
.target {
background-color: #e4c1f9;
height: 30px;
}
const App = () => {
const containerRef = useRef(null);
const targetRef = useRef(null);
const { isDragging } = useDrag({
containerRef,
targetRefList: [targetRef],
});
useEffect(() => {
console.log(
`Current state value: ${isDragging ? 'dragging' : 'not dragging'}`
);
}, [isDragging]);
return (
<div className="box" ref={containerRef}>
<div className="target" ref={targetRef} />
</div>
);
};