Gestures
Motion extends React's basic set of event listeners with a simple yet powerful set of UI gestures.
The motion
component currently has support for hover, tap, pan, drag and inView.
Each gesture has both a set of event listeners and a while-
animation prop.
Animation props
motion
components provide multiple gesture animation props: whileHover
, whileTap
, whileFocus
, whileDrag
and whileInView
. These can define animation targets to temporarily animate to while a gesture is active.
All props can be set either as a target of values to animate to, or the name of any variants defined via the variants
prop. Variants will flow down through children as normal.
Gestures
Hover
The hover gesture detects when a pointer hovers over or leaves a component.
It differs from onMouseEnter
and onMouseLeave
in that hover is guaranteed to only fire as a result of actual mouse events (as opposed to browser-generated mice events emulated from touch input).
Tap
The tap gesture detects when the primary pointer (like a left click or first touch point) presses down and releases on the same component.
It will fire a tap
event when the tap or click ends on the same component it started on, and a tapCancel
event if the tap or click ends outside the component.
If the tappable component is a child of a draggable component, it'll automatically cancel the tap gesture if the pointer moves further than 3 pixels during the gesture.
Accessibility
Elements with tap events are keyboard-accessible.
Any element with a tap prop will be able to receive focus and Enter
can be used to trigger tap events on focused elements.
Pressing
Enter
down will triggeronTapStart
andwhileTap
Releasing
Enter
will triggeronTap
If the element loses focus before
Enter
is released,onTapCancel
will fire.
Pan
The pan gesture recognises when a pointer presses down on a component and moves further than 3 pixels. The pan gesture is ended when the pointer is released.
Pan doesn't currently have an associated while-
prop.
Note: For pan gestures to work correctly with touch input, the element needs touch scrolling to be disabled on either x/y or both axis with the touch-action
CSS rule.
Drag
The drag gesture applies pointer movement to the x and/or y axis of the component.
By default, when the drag ends the element will perform an inertia animation with the ending velocity.
This can be disabled by setting dragMomentum
to false
, or changed via the dragTransition
prop.
It's also possible to set dragConstraints
, either as an object with top
, left
, right
, and bottom
values, measured in pixels.
Or, it can accept a ref
to another component created with React's useRef
hook. This ref
should be passed both to the draggable component's dragConstraints
prop, and the ref
of the component you want to use as constraints.
By default, dragging the element outside the constraints will tug with some elasticity. This can be changed by setting dragElastic
to a value between 0
and 1
, where 0
equals no motion and 1
equals full motion outside the constraints.
Focus
The focus gesture detects when a component gains or loses focus by the same rules as the CSS :focus-visible selector.
Typically, this is when an input
receives focus by any means, and when other elements receive focus by accessible means (like via keyboard navigation).
Event propagation
Children can stop pointer events propagating to parent motion
components using the Capture
React props.
For instance, a child can stop drag and tap gestures and their related while
animations from firing on parents by passing e.stopPropagation()
to onPointerDownCapture
.
Note: SVG filters
Gestures aren't recognised on SVG filter
components, as these elements don't have a physical presence and therefore don't receive events.
You can instead add while-
props and event handlers to a parent and use variants to animate these elements.
A Motion+ membership will give you early access to features & content, access to our private Discord, and more.
It's a one-time fee that grants lifetime access. No subscription necessary!