Gestures
Every motion.<tag> component accepts four gesture props that animate to a target state for the duration of the gesture and restore on exit. They compose freely with initial, animate, exit, and transition.
<motion.button
whileHover={{ scale: 1.05 }}
whileTap={{ scale: 0.95 }}
whileFocus={{ scale: 1.05, borderColor: '#3b82f6' }}
>
Click me
</motion.button><motion.button
whileHover={{ scale: 1.05 }}
whileTap={{ scale: 0.95 }}
whileFocus={{ scale: 1.05, borderColor: '#3b82f6' }}
>
Click me
</motion.button>| Prop | Triggered by | Notes |
|---|---|---|
whileHover | Pointer enters/leaves | True-hover gating (touch devices don’t trigger) |
whileTap | Press start/end on element | Keyboard accessible (Enter/Space) |
whileFocus | Focus enters/leaves | Pairs with :focus-visible for accessibility |
whileInView | Element enters/leaves viewport | Backed by IntersectionObserver |
Each gesture prop has companion lifecycle callbacks (onHoverStart / onHoverEnd, onTapStart / onTap / onTapCancel, onFocusStart / onFocusEnd, onInViewStart / onInViewEnd) for side effects that aren’t expressible as style changes (analytics, focus management, etc.).
whileHover
Animate while the pointer is over the element.
<motion.button
whileHover={{ scale: 1.05, backgroundColor: '#3b82f6' }}
onHoverStart={() => console.log('hover start')}
onHoverEnd={() => console.log('hover end')}
>
Hover me
</motion.button><motion.button
whileHover={{ scale: 1.05, backgroundColor: '#3b82f6' }}
onHoverStart={() => console.log('hover start')}
onHoverEnd={() => console.log('hover end')}
>
Hover me
</motion.button>True-hover gating. whileHover uses CSS media queries ((hover: hover) and (pointer: fine)) to gate the hover state. Touch devices that emit synthetic hover events on tap don’t trigger the gesture — the hover animation stays inert on phones and tablets, matching how :hover CSS pseudo-class behaves in modern stylesheets.
whileTap
Animate while the element is being pressed.
<motion.button
whileTap={{ scale: 0.95 }}
onTapStart={() => console.log('press down')}
onTap={() => console.log('press complete (no cancel)')}
onTapCancel={() => console.log('pointer left before release')}
>
Tap me
</motion.button><motion.button
whileTap={{ scale: 0.95 }}
onTapStart={() => console.log('press down')}
onTap={() => console.log('press complete (no cancel)')}
onTapCancel={() => console.log('pointer left before release')}
>
Tap me
</motion.button>Keyboard accessible. Pressing Enter or Space on a focused element fires the same tap lifecycle as a pointer press. Combine with whileFocus to make tap interactions discoverable for keyboard users.
whileTap, onTap and onTapStart add tabindex="0" unless you set tabindex yourself, matching Motion. This applies to every tag, including buttons and links, and to server-rendered markup.
onTap fires only when the press completes on the element. If the pointer drags off before release, onTapCancel fires instead.
Tuning the tap transition
Without a transition, taps use Motion’s per-value defaults — a spring for transforms, which intentionally overshoots rest by a hair on release (the “springy” Framer feel). The resolution order matches Framer: an inline whileTap.transition shapes the press, the base variant’s transition shapes the release, the component transition prop (or <MotionConfig>) covers both, and per-value defaults fill the rest.
If a transform must never pass its resting value — e.g. a scale press on an element where any growth is visible — pin the release with a critically damped spring (bounce: 0) or an ease-out tween:
<motion.button
whileTap={{ scale: 0.95 }}
animate={{ scale: 1, transition: { type: 'spring', visualDuration: 0.2, bounce: 0 } }}
>
No overshoot on release
</motion.button><motion.button
whileTap={{ scale: 0.95 }}
animate={{ scale: 1, transition: { type: 'spring', visualDuration: 0.2, bounce: 0 } }}
>
No overshoot on release
</motion.button>Double tap, long press and repeat
The tap prop changes when a tap counts. It applies to onTapStart, onTap, onTapCancel and whileTap, matching Motion 14.10.
| Option | Default | What it does |
|---|---|---|
count | 1 | Quick, consecutive presses needed for onTap. |
countTimeout | 0.3 | Max seconds between presses. A later press cancels the sequence. |
hold | 0 | Seconds the press must be held for onTap. Releasing earlier cancels. |
repeat | — | While held, onTap fires every repeat seconds. |
<!-- Double tap -->
<motion.div tap={{ count: 2 }} onTap={onDoubleTap} /><!-- Double tap -->
<motion.div tap={{ count: 2 }} onTap={onDoubleTap} /><!-- Long press -->
<motion.div tap={{ hold: 0.5 }} whileTap={{ scale: 0.9 }} onTap={onLongPress} /><!-- Long press -->
<motion.div tap={{ hold: 0.5 }} whileTap={{ scale: 0.9 }} onTap={onLongPress} /><!-- Stepper: onTap fires every 0.1 seconds while held -->
<motion.button tap={{ repeat: 0.1 }} onTap={increment} /><!-- Stepper: onTap fires every 0.1 seconds while held -->
<motion.button tap={{ repeat: 0.1 }} onTap={increment} />onTapStartandwhileTapstart on the first press, so the element reacts straight away.onTapfires when the gesture completes, and on eachrepeat.whileTapstays on between repeats.- Otherwise
onTapCancelfires: a press that is too late, released too early, or released off the element. tapalone does not turn the gesture on. Pair it withonTap,onTapStart,onTapCancelorwhileTap.- Keyboard presses (Enter) follow the same rules.
globalTapTarget and propagate. globalTapTarget attaches the tap’s start listener to window, so a press anywhere starts the gesture (Motion marks it as not publicly supported). By default a tap on a child also starts the taps of its motion ancestors. Set propagate={{ tap: false }} on the child to stop that:
<motion.div onTap={onCardTap}>
<motion.button onTap={onLike} propagate={{ tap: false }}>Like</motion.button>
</motion.div><motion.div onTap={onCardTap}>
<motion.button onTap={onLike} propagate={{ tap: false }}>Like</motion.button>
</motion.div>Try all three on the tap options example.
Interrupts carry momentum
Gesture channels ride persistent motion values, so interrupting a spring re-targets the same value — position and velocity carry into the next animation, exactly as in Framer Motion. Press an element while its hover spring is still climbing and the press animation launches from that live upward velocity: the element keeps growing for a beat before curving into the shrink, instead of reversing from a dead stop. Rapid flicks across a hover boundary read as one continuous elastic motion.
This holds for stiffness/damping springs and, from Motion 14.12, for visualDuration/bounce springs; a duration spring starts from rest.
There is nothing to configure — it applies to every whileHover/whileTap interrupt. See it (and feel it) on the velocity interrupts example.
whileFocus
Animate while the element has keyboard focus.
<motion.input
whileFocus={{ scale: 1.02, borderColor: '#3b82f6' }}
onFocusStart={() => console.log('focus enter')}
onFocusEnd={() => console.log('focus leave')}
/><motion.input
whileFocus={{ scale: 1.02, borderColor: '#3b82f6' }}
onFocusStart={() => console.log('focus enter')}
onFocusEnd={() => console.log('focus leave')}
/>Pairs well with whileHover on inputs and buttons so the focus animation matches what hover feels like — important for users who navigate with Tab instead of pointer.
whileInView
Animate when the element enters the viewport. Backed by IntersectionObserver.
<motion.div
initial={{ opacity: 0, y: 40 }}
whileInView={{ opacity: 1, y: 0 }}
viewport={{ once: true, amount: 0.5, margin: '-50px' }}
transition={{ duration: 0.6 }}
onInViewStart={() => console.log('entered viewport')}
onInViewEnd={() => console.log('left viewport')}
>
Fades in on scroll
</motion.div><motion.div
initial={{ opacity: 0, y: 40 }}
whileInView={{ opacity: 1, y: 0 }}
viewport={{ once: true, amount: 0.5, margin: '-50px' }}
transition={{ duration: 0.6 }}
onInViewStart={() => console.log('entered viewport')}
onInViewEnd={() => console.log('left viewport')}
>
Fades in on scroll
</motion.div>viewport options
| Option | Type | Default | Description |
|---|---|---|---|
once | boolean | false | Fire on the first enter and latch — the element never reverts to its initial state |
amount | number \| 'some' \| 'all' | 'some' | Fraction of the element that must be visible (number 0–1) or named threshold |
margin | string | '0px' | CSS margin string applied to the IntersectionObserver root box (e.g. '-50px 0px') |
root | HTMLElement | viewport | Custom scroll container — defaults to the page viewport |
once: true for reveal animations prevents the “scroll up, see it again” effect that’s usually unwanted for content-reveal patterns.
whilePinch
Animate while the element is being pinched with two touches or a trackpad, alongside the pinch prop that scales, rotates and moves it. Both need pinchFeatures loaded through LazyMotion, even on motion.* components; see Pinch.
Composing with transition
Every gesture prop accepts an optional transition inside the target object so a gesture can have its own timing distinct from the component’s default transition:
<motion.div
transition={{ duration: 0.3 }}
whileHover={{
scale: 1.05,
transition: { duration: 0.15 }
}}
whileTap={{
scale: 0.95,
transition: { type: 'spring', stiffness: 800 }
}}
/><motion.div
transition={{ duration: 0.3 }}
whileHover={{
scale: 1.05,
transition: { duration: 0.15 }
}}
whileTap={{
scale: 0.95,
transition: { type: 'spring', stiffness: 800 }
}}
/>This gives quick feedback on hover and a snappy spring on tap while keeping the default for any non-gesture animation.
Hook variants
For non-component cases (vanilla DOM, custom logic that isn’t a <motion.div>), use the hook form where one exists:
useInView—IntersectionObserver-backed in-view detection without a motion componentwhileHover,whileTap, andwhileFocusare best used via the motion-component props. There’s no dedicated hook for those three because the prop form is the recommended path; if you need the same behaviour outside a motion component, wire up a native listener (pointerenter/leave,pointerdown/up,focus/blur) directly.
Based on Motion’s gesture animations API.