motion
The motion
component drives most animations in Motion for React.
There's a motion
component for every HTML and SVG element, for instance motion.div
, motion.circle
etc. Think of it as a normal React component, supercharged for 120fps animation and gestures.
Usage
Import motion
from Motion:
Now you can use it exactly as you would any normal HTML/SVG component:
But you also gain access to powerful animation APIs like the animate
, layout
, whileInView
props and much more.
Checkout the Animation guide for a full overview on animations in Motion for React.
Performance
motion
components animate values outside the React render cycle for improved performance.
Using motion values instead of React state to update style
will also avoid re-renders.
Server-side rendering
motion
components are fully compatible with server-side rendering, meaning the initial state of the component will be reflected in the server-generated output.
This is with the exception of some SVG attributes like transform
which require DOM measurements to calculate.
Custom components
Any React component can be supercharged into a motion
component by passing it to motion.create()
as a function:
Important: Make sure not to call motion.create()
within another React render function! This will make a new component every render, breaking your animations.
It's also possible to pass strings to motion.create
, which will create custom DOM elements.
By default, all motion
props (like animate
etc) are filtered out of the props
forwarded to the provided component. By providing a forwardMotionProps
config, the provided component will receive these props.
Props
motion
components accept the following props.
Animation
initial
The initial visual state of the motion
component.
This can be set as an animation target:
Variants:
Or set as false
to disable the enter animation and initially render as the values found in animate
.
animate
A target to animate to on enter, and on update.
Can be set as an animation target:
Or variants:
exit
A target to animate to when a component is removed from the tree. Can be set either as an animation target, or variant.
Note: Owing to React limitations, the component being removed must be a direct child of AnimatePresence
to enable this animation.
transition
The default transition for this component to use when an animation prop (animate
, whileHover
etc) has no transition
defined.
variants
The variants for this component.
style
The normal React DOM style
prop, with added support for motion values and independent transforms.
onUpdate
Callback triggered every frame any value on the motion
component updates. It's provided a single argument with the latest values.
onAnimationStart
Callback triggered when any animation (except layout animations, see onLayoutAnimationStart
) starts.
It's provided a single argument, with the target or variant name of the started animation.
onAnimationComplete
Callback triggered when any animation (except layout animations, see onLayoutAnimationComplete
) completes.
It's provided a single argument, with the target or variant name of the completed animation.
Hover
whileHover
Target or variants to label to while the hover gesture is active.
onHoverStart
Callback function that fires when a pointer starts hovering over the component. Provided the triggering PointerEvent
.
onHoverEnd
Callback function that fires when a pointer stops hovering over the component. Provided the triggering PointerEvent
.
Tap
whileTap
Target or variants to label to while the tap gesture is active.
onTapStart
Callback function that fires when a pointer starts pressing the component. Provided the triggering PointerEvent
.
onTap
Callback function that fires when a pointer stops pressing the component and the pointer was released inside the component. Provided the triggering PointerEvent
.
onTapCancel
Callback function that fires when a pointer stops pressing the component and the pointer was released outside the component. Provided the triggering PointerEvent
.
Focus
whileFocus
Target or variants to label to while the focus gesture is active.
Pan
onPan
Callback function that fires when the pan gesture is recognised on this element.
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.
Pan and drag events are provided the origin PointerEvent
as well as an object info
that contains x
and y
point values for the following:
point
: Relative to the device or page.delta
: Distance since the last event.offset
: Distance from the original event.velocity
: Current velocity of the pointer.
onPanStart
Callback function that fires when a pan gesture starts. Provided the triggering PointerEvent
and info
.
onPanEnd
Callback function that fires when a pan gesture ends. Provided the triggering PointerEvent
and info
.
Drag
drag
Default: false
Enable dragging for this element. Set true
to drag in both directions. Set "x"
or "y"
to only drag in a specific direction.
whileDrag
Target or variants to label to while the drag gesture is active.
dragConstraints
Applies constraints on the draggable area.
Set as an object of optional top
, left
, right
, and bottom
values, measured in pixels:
Or as a ref
to another element to use its bounding box as the draggable constraints:
dragSnapToOrigin
Default: false
If true
, the draggable element will animate back to its center/origin when released.
dragElastic
Default: 0.5
The degree of movement allowed outside constraints. 0
= no movement, 1
= full movement.
Set to 0.5
by default. Can also be set as false
to disable movement.
By passing an object of top
/right
/bottom
/left
, individual values can be set per constraint. Any missing values will be set to 0
.
dragMomentum
Default: true
Apply momentum from the pan gesture to the component when dragging finishes. Set to true
by default.
dragTransition
Allows you to change dragging momentum transition. When releasing a draggable element, an animation with type "inertia"
starts. The animation is based on your dragging velocity. This property allows you to customize it.
dragDirectionLock
Default: false
Locks drag direction into the soonest detected direction. For example, if the component is moved more on the x
axis than y
axis before the drag gesture kicks in, it will only drag on the x
axis for the remainder of the gesture.
dragPropagation
Default: false
Allows drag gesture propagation to child components.
dragControls
Usually, dragging is initiated by pressing down on a component and moving it. For some use-cases, for instance clicking at an arbitrary point on a video scrubber, we might want to initiate dragging from a different component than the draggable one.
By creating a dragControls
using the useDragControls
hook, we can pass this into the draggable component's dragControls
prop. It exposes a start
method that can start dragging from pointer events on other components.
Note: Given that by setting dragControls
you are taking control of initiating the drag gesture, it is possible to disable the draggable element as the initiator by setting dragListener={false}
.
dragListener
Determines whether to trigger the drag gesture from event listeners. If passing dragControls
, setting this to false
will ensure dragging can only be initiated by the controls, rather than a pointerdown
event on the draggable element.
onDrag
Callback function that fires when the drag gesture is recognised on this element.
Pan and drag events are provided the origin PointerEvent
as well as an object info
that contains x
and y
point values for the following:
point
: Relative to the device or page.delta
: Distance since the last event.offset
: Distance from the original event.velocity
: Current velocity of the pointer.
onDragStart
Callback function that fires when a drag gesture starts. Provided the triggering PointerEvent
and info
.
onDragEnd
Callback function that fires when a drag gesture ends. Provided the triggering PointerEvent
and info
.
onDirectionLock
Callback function that fires a drag direction is determined.
Viewport
whileInView
Target or variants to label to while the element is in view.
viewport
Options to define how the element is tracked within the viewport.
Available options:
once
: Iftrue
, once element enters the viewport it won't detect subsequent leave/enter events.root
: Theref
of an ancestor scrollable element to detect intersections with (instead ofwindow
).margin
: A margin to add to the viewport to change the detection area. Defaults to"0px"
. Use multiple values to adjust top/right/bottom/left, e.g."0px -20px 0px 100px"
.amount
: The amount of an element that should enter the viewport to be considered "entered". Either"some"
,"all"
or a number between0
and1
. Defaults to"some"
.
onViewportEnter
Callback function that fires when an element enters the viewport. Provided the IntersectionObserverEntry
with details of the intersection event.
onViewportLeave
Callback function that fires when an element enters the viewport. Provided the IntersectionObserverEntry
with details of the intersection event.
Layout
layout
Default: false
If true
, this component will animate changes to its layout.
If set to "position"
or "size"
, only its position or size will animate, respectively.
layoutId
If set, this component will animate changes to its layout. Additionally, when a new element enters the DOM and an element already exists with a matching layoutId
, it will animate out from the previous element's size/position.
If the previous component remains in the tree, the two elements will crossfade.
layoutDependency
By default, layout changes are detected every render. To reduce measurements and thus improve performance, you can pass a layoutDependency
prop. Measurements will only occur when this value changes.
layoutScroll
For layout animations to work correctly within scrollable elements, their scroll offset needs measuring. For performance reasons, Framer Motion doesn't measure the scroll offset of every ancestor. Add the layoutScroll
prop to elements that should be measured.
layoutRoot
For layout animations to work correctly within position: fixed
elements, we need to account for page scroll. Add layoutRoot
to mark an element as position: fixed
.
onLayoutAnimationStart
A callback to run when a layout animation starts.
onLayoutAnimationComplete
A callback to run when a layout animation completes.
Advanced
inherit
Set to false
to prevent a component inheriting or propagating changes in a parent variant.
custom
Custom data to pass through to dynamic variants.
transformTemplate
By default, transforms are applied in order of translate
, scale
, rotate
and skew
.
To change this, transformTemplate
can be set as a function that accepts the latest transforms and the generated transform string and returns a new transform string.
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!