react-use-draggable-scroll-safe
v0.5.4
Published
## This is a fork based on the great work by [rfmiotto](https://github.com/rfmiotto) The main difference is that this version does not crash when passed a null or undefined reference (ref) therefore makes it suitable for use in conditionally rendederd com
Downloads
3,167
Readme
useDraggable Hook (Safe version)
This is a fork based on the great work by rfmiotto
The main difference is that this version does not crash when passed a null or undefined reference (ref) therefore makes it suitable for use in conditionally rendederd components.
useDraggable is a React hook that allows a wrapping div to have a draggable scroll with an inertial effect. It is completely unstyled and just adds the functionality you are looking for so your application gives the best user experience possible. It works in both x- and y-coordinate directions.
See DEMO.
Why useDraggable?
Differently from other hooks designed for the same purpose, this hook does not rely on any state changes. The functionality is built entirely on event listeners. This means that the wrapping div and its children elements are not re-rendered, resulting in a better performance.
Installation
npm install react-use-draggable-scroll-safe
How to use
All you have to do is to create a reference to the wrapping div and pass it as parameter to to the useDraggable hook. The hook is totally unstyled. You can use any library of your choice to style the div and the child components as you would normally do. In the example below, we use TailwindCSS to illustrate.
Just recapping some basics of CSS that you will probably use along with this hook: It is important to set overflow-x: scroll;
property in the CSS of the wrapping div to create the scroll (same goes for y-direction, if that is your case). To prevent a
flex item from growing or shrinking, use the CSS property flex: none;
.
In Javascript:
import { useRef } from "react";
import { useDraggable } from "react-use-draggable-scroll";
export default function MyComponent() {
const ref = useRef(); // We will use React useRef hook to reference the wrapping div:
const { events } = useDraggable(ref); // Now we pass the reference to the useDraggable hook:
return (
<div
className="flex max-w-xl space-x-3 overflow-x-scroll scrollbar-hide"
{...events}
ref={ref} // add reference and events to the wrapping div
>
<div className="flex-none w-52 h-32 bg-red-200" />
<div className="flex-none w-52 h-32 bg-red-200" />
<div className="flex-none w-52 h-32 bg-red-200" />
<div className="flex-none w-52 h-32 bg-red-200" />
<div className="flex-none w-52 h-32 bg-red-200" />
<div className="flex-none w-52 h-32 bg-red-200" />
<div className="flex-none w-52 h-32 bg-red-200" />
<div className="flex-none w-52 h-32 bg-red-200" />
<div className="flex-none w-52 h-32 bg-red-200" />
</div>
);
}
In Typescript:
import { useRef } from "react";
import { useDraggable } from "react-use-draggable-scroll";
export default function MyComponent(): JSX.Element {
// We will use React useRef hook to reference the wrapping div:
const ref =
useRef<HTMLDivElement>() as React.MutableRefObject<HTMLInputElement>;
const { events } = useDraggable(ref); // Now we pass the reference to the useDraggable hook:
return (
<div
className="flex max-w-xl space-x-3 overflow-x-scroll scrollbar-hide"
{...events}
ref={ref} // add reference and events to the wrapping div
>
<div className="flex-none w-52 h-32 bg-red-200" />
<div className="flex-none w-52 h-32 bg-red-200" />
<div className="flex-none w-52 h-32 bg-red-200" />
<div className="flex-none w-52 h-32 bg-red-200" />
<div className="flex-none w-52 h-32 bg-red-200" />
<div className="flex-none w-52 h-32 bg-red-200" />
<div className="flex-none w-52 h-32 bg-red-200" />
<div className="flex-none w-52 h-32 bg-red-200" />
<div className="flex-none w-52 h-32 bg-red-200" />
</div>
);
}
Additional settings:
activeMouseButton
: Change which mouse button starts a scroll
By default, holding left mouse button will start a scroll. However, you can also use the middle or right mouse button to start a scroll.
Accepts "Left" | "Right" | "Middle
const { events } = useDraggable(ref, {
activeMouseButton?: "Middle"; // Sets which mouse button starts a scroll
});
applyRubberBandEffect
: Rubber Band Effect
It is possible to toggle a rubber band effect on and off for when the user scrolls past the end of the container. This effect is turned off by default to avoid conflicting CSS style rules in code that uses earlier versions of this hook.
const { events } = useDraggable(ref, {
applyRubberBandEffect: true, // activate rubber band effect
});
:warning: If you are using rubber band effect: This effect is applied using the
transform
CSS property. User-defined styles can be overridden whenapplyRubberBandEffect
istrue
(default value isfalse
).
decayRate
: Control the decay rate of the inertial effect
You can also control the decay rate of the inertial effect by using an optional parameter. The default value is 0.95, which means that at the speed will decay 5% of its current value at every 1/60 seconds.
const { events } = useDraggable(ref, {
decayRate: 0.96, // specify the decay rate
});
safeDisplacement
: Control the drag sensitivity
Finally, you can control drag sensitivity by using an optional parameter that states the minimum distance in order to distinguish an intentional drag movement from an unwanted one, which should be instead considered as a click. The default value is 10, which means that when a drag movement travels for 10 pixels or less it is considered unintentional. In this scenario, the drag operation would still be performed, but the closing mouse-up event would still be propagated to the rest of the DOM.
const { events } = useDraggable(ref, {
safeDisplacement: 11, // specify the drag sensitivity
});
isMounted
: Determine if ref is available or not, default true
In some use cases, such as you need to use useImperativeHandle
,
you will need to wait for the component to be rendered and the Ref to be accessible before
using the useDraggable
hook. In this case, use isMounted
as a controllable switch.
const { events } = useDraggable(ref, {
isMounted: true,
});
Contributing
See CONTRIBUTING.md.