docs/guides/how-we-use-dom-events.md
This page details how we use DOM input events, what we do with them, and how you can build things on top of our usage. Generally you will not need to know this information but it can be helpful if you are also binding your own event handlers to the window or to a drag handle. ā ļø Note: due to a bug in webkit, particular events such as
mousemovewill not correctly setevent.defaultPreventedtotruewhenevent.preventDefault()is called. You can follow progress on this issue here.
This page assumes a working knowledge of DOM events. For a good introduction to DOM events see:
Without needing going into all the details below, here are the safest event handlers to build on top of react-beautiful-dnd:
These can be added on the drag handle, anywhere else higher on the tree or to the window directly.
onClick: the event.defaultPrevented property will be set to true if occurred as a part of the drag interaction. This is true even if the drag was not finished with a pre-click action such as mouseup or touchend. See sloppy clicks and click prevention.onKeyDown: the event.defaultPrevented property will be set to true if it was used as a part of a drag.When we use an input event as part of a drag and drop interaction we generally call event.preventDefault() on the event to opt out of standard browser behaviour for the event. We do not stop the propagation of events that we call event.preventDefault() on so even though we may use a mousemove event for dragging we will not block that event from being published (propagating) and received by your event handlers.
event.preventDefault()event.stopPropagation()We add all event handlers to the window in the capture phase. What this means is as long as you are applying your events handlers in the bubbling phase (which is the default for event handlers) then behaviour of events will be as described on this page.
In order to know if we have already used the event for the purpose of drag and drop you need to check the event.defaultPrevented property.
So let's say you want to add a window click handler. You could do something like this:
window.addEventListener('click', (event: MouseEvent) => {
// event has already been used for drag and drop
if (event.defaultPrevented) {
return;
}
doMyCoolThing();
});
Some user events have a direct impact on a drag: such as a mousemove when dragging with a mouse or the up arrow <kbd>ā</kbd> keydown event while dragging with a keyboard. These direct events will have event.preventDefault() called on them to prevent their default browser behaviours. Some events indirectly impact a drag such as a resize event which cancels a drag. For events that indirectly impact a drag we do not call event.preventDefault() on them. Generally indirect events that impact drag are events that cancel a drag such as resize and orientationchange events.
mousedownpreventDefault() is called on mousedown šThis is the only known exception to our rule set. It is unfortunate that it is the first one to appear in this guide!
When the user first performs a mousedown on a drag handle we are not sure if they are intending to click or drag. Ideally we would not call preventDefault() on this event as we are not sure if it is a part of a drag. However, we need to call preventDefault() in order to avoid the item obtaining focus as it has a tabIndex.
preventDefault() not called on mousemoveThe user needs to move a small threshold before we consider the movement to be a drag. In this period of time we do not call preventDefault() on any mousemove events as we are not sure if they are dragging or just performing a sloppy click
preventDefault() not called on the event that caused the pending drag to end (such as mouseup and keydown). Any keydown event that is firered while there is a pending drag will be considered an indirect cancelpreventDefault() is not called on the subsequent click event if there is onepreventDefault() is called on mousemove eventspreventDefault() is called on a few keydown events to prevent their standard browser behaviourpreventDefault() is not called on keyup events even if the keydown was preventedpreventDefault() is called on a mouseup if it ended the dragpreventDefault() is called on a escape <kbd>esc</kbd> keydown if it ended the drag as it directly ended the dragpreventDefault() is called on the next click event regardless of how the drag ended. See sloppy clicks and click preventionpreventDefault() is not called on other events such as resize that indirectly ended a dragpreventDefault() is not called on keyup events even if they caused the drag to endThe logic for touch dragging works in a similar way to mouse dragging
touchstartpreventDefault() is not called on touchstart.When a user presses their finger (or other input) on a <Draggable /> we are not sure if they where intending to tap, force press, scroll the container or drag. Because we do not know what the user is trying to do yet we do not call preventDefault() on the event.
preventDefault() is not called on any eventsA user can start a drag by holding their finger š on an element for a small period of time š (long press). If the user moves during this time with touchmove then we do not call preventDefault() on the event.
It is possible to cancel a touch drag with over events such as an orientationchange or a touchcancel. We do not call preventDefault on these events.
preventDefault() is called on touchmove eventsāļø
preventDefault() is called on touchendpreventDefault() is called on touchcancelpreventDefault() is called on an escape <kbd>esc</kbd> keydown as a direct cancel. preventDefault() is not call on any other keydown as it is an indirect cancel.preventDefault() is not called on other events such as orientationchange that can cancel a dragSee our force press guide
<Draggable shouldRespectForcePress={false} /> (the default)Opting out of force change events by default for a more consistent drag experience
preventDefault() is called on all touchforcechange events after a touchstart event is fired and a pending drag timer has started<Draggable shouldRespectForcePress />Respecting standard force touch interactions
preventDefault() is not called on touchforcechange if a drag has not started yetpreventDefault() is not called on touchforcechange a drag that has started but no movement has occurred yet. The force press cancels the drag and is an indirect cancel.preventDefault() is called after on touchforcechange a drag has started and a touchmove has fired. This is defensive as a force press touchforcechange should not occur after a touchmove.We only use
keydownevents for keyboard dragging sokeyupevents never havepreventDefault()called on them
preventDefault()is called onkeydown
Unlike mouse dragging a keyboard drag starts as soon as the user presses the spacebar <kbd>space</kbd>. This initial keyboard interaction has event.preventDefault() called on it.
preventDefault() is called on a keydown event if the event is used as part of the drag (such as the up arrow <kbd>ā</kbd>)preventDefault() is called on keydown events were we want to block the stanard browser behaviours (such as enter for submission)preventDefault() is not called on keydown events that we do not use for the dragpreventDefault() is called on a keydown if it is the spacebar <kbd>space</kbd> key as it is dropping the itempreventDefault() is called on a keydown if it is the escape <kbd>esc</kbd> key as it is explicitly cancelling the dragpreventDefault() is not called on events that indirectly cancel a drag such as resize or mousedown.Background: please see Setup problem detection and error recovery.
If an rbd error is thrown and is caught by our window error listener, we will call event.preventDefault() on the error event to mark it as consumed. We do this as well as aborting the existing drag and logging warnings in development mode.