useAnimation

Hook to implement animation on elements.

See: Web Animations API.

Demo

INFO

The component uses useAnimation to compute an animation on p element. Use the buttons to perform action on animation.

Loading demo…

Show source code

import { useAnimation } from "../../../..";

export const UseAnimation = () => {
	const { ref, playAnimation, pauseAnimation, finishAnimation, reverseAnimation } = useAnimation({
		keyFrames: [
			{ clipPath: 'circle(20% at 0% 30%)' },
			{ clipPath: 'circle(20% at 50% 80%)' },
			{ clipPath: 'circle(20% at 100% 30%)' },
		],
		immediate: true,
		opts: {
			duration: 3000,
			iterations: 2,
			direction: 'alternate',
			easing: 'cubic-bezier(0.46, 0.03, 0.52, 0.96)',
		}
	});

	return <div>
		<p ref={ref} style={{ color: '#d23e49', fontSize: '3rem', lineHeight: 1, fontWeight: 800, display: 'inline-flex', padding: '0 5rem' }}>useAnimate</p>
		<div style={{ display: 'flex', justifyContent: "center", gap: 20 }}>
			<button onClick={playAnimation}>Play</button>
			<button onClick={pauseAnimation}>Pause</button>
			<button onClick={reverseAnimation}>Reverse</button>
			<button onClick={finishAnimation}>Finish</button>
		</div>
	</div>
}

Types

UseAnimationProps

Configuration object accepted by useAnimation.

Wraps the Web Animations API (Element.animate()) options with additional React lifecycle hooks.

Property	Type	Required	Description
keyFrames	Keyframe[] \| PropertyIndexedKeyframes \| null	✓	Keyframes to animate. Accepts any format supported by Element.animate(): - Keyframe[] — an array of keyframe objects (e.g. [{ opacity: 0 }, { opacity: 1 }]). - PropertyIndexedKeyframes — an object mapping CSS properties to arrays of values. - null — no keyframes (the animation is effectively disabled).
immediate	boolean		When true, the animation starts immediately when the element mounts (before a manual call to playAnimation()).
opts	number \| KeyframeAnimationOptions		Timing options forwarded to Element.animate(). Accepts either: - A number representing the total duration in milliseconds. - A KeyframeAnimationOptions object (e.g. { duration: 500, easing: "ease-in-out" }).
onFinish	(this: Animation, evt: AnimationPlaybackEvent) => void		Called when the animation completes (the finish event fires).
onRemove	(this: Animation, evt: Event) => void		Called when the animation is removed from its element's effect stack.
onCancel	(this: Animation, evt: AnimationPlaybackEvent) => void		Called when the animation is cancelled.
onError	(err: unknown) => void		Called when the Web Animations API throws an unexpected error.

UseAnimationResult

• @template T Type of the target DOM element (defaults to Element).

Result object returned by useAnimation.

Property	Type	Required	Description
isSupported	boolean	✓	true when the Web Animations API (element.animate) is available in the current browser. When false, all control functions are no-ops.
ref	RefCallback<T>	✓	Callback ref to attach to the DOM element you want to animate. The animation is created and bound to the element when this ref is set.
playAnimation	() => void	✓	Resumes or starts the animation (calls Animation.play()).
pauseAnimation	() => void	✓	Pauses the animation at its current position (calls Animation.pause()).
finishAnimation	() => void	✓	Immediately jumps the animation to its end state (calls Animation.finish()).
cancelAnimation	() => void	✓	Cancels the animation, removing all effects and resetting to the initial state (calls Animation.cancel()).
persistAnimation	() => void	✓	Marks the animation as persistent so it is not automatically removed from the element's effect stack (calls Animation.persist()).
reverseAnimation	() => void	✓	Plays the animation in reverse (calls Animation.reverse()).
commitStyles	() => void	✓	Applies the current computed animation styles directly to the element and then cancels the animation (calls Animation.commitStyles()). Useful for preserving the final animation state after removal.
updatePlaybackRate	(playbackRate: number) => void	✓	Changes the playback rate of the animation without adjusting its current time.