Getting Started

Seamlessly integrate Motion-powered animations into your Svelte projects using Mercury.

The following guide will walk you through the process of installing Mercury.

Installation

Install Mercury together with Motion, which it runs on:

npm install @omicrxn/mercury motion

pnpm add @omicrxn/mercury motion

yarn add @omicrxn/mercury motion

bun add @omicrxn/mercury motion

nub add @omicrxn/mercury motion

aube add @omicrxn/mercury motion

Mercury requires Svelte 5. Motion is a peer dependency, so your app and Mercury share one copy of it — import Motion’s utilities (stagger, motionValue, easing functions…) straight from motion.

Animating Elements

Mercury brings Motion’s animation props to Svelte attachments. Add mercury() to an element and give it the props you’d give a <motion.div>:

<script lang="ts">
	import { mercury } from '@omicrxn/mercury';
</script>

<div
	{@attach mercury({
		initial: { opacity: 0, scale: 0.95 },
		animate: { opacity: 1, scale: 1 },
		whileHover: { scale: 1.05 },
		transition: { type: 'spring', duration: 0.3, bounce: 0 }
	})}
></div>

<script lang="ts">
	import { type AnimationInstance } from '@omicrxn/mercury';
	import { mercury } from '@omicrxn/mercury';
	let { animation = $bindable() }: { animation?: AnimationInstance } = $props();
</script>

<div class="flex flex-col gap-4">
	<h2 class="text-xl font-bold">Basic Animation</h2>
	<div
		class="box w-16 h-16 bg-demo-fill rounded-md border border-demo-stroke"
		style="opacity: 0; transform: scale(0.95);"
		{@attach mercury({
			animate: { opacity: [0, 1], scale: [0.95, 1] },
			instance: (instance) => {
				animation = instance;
			},
			transition: { ease: [0.19, 1, 0.22, 1], duration: 0.25 }
		})}
	></div>

	<button
		type="button"
		class="min-h-11 rounded-md border border-demo-stroke px-3 text-sm font-medium"
		onclick={() => {
			animation?.play();
		}}>Play</button
	>
</div>

From here:

• Animate — initial, animate, transitions, springs and keyframes.
• Variants — named states orchestrated across children.
• Gestures — hover, tap, focus, in-view, pan and drag.
• Presence — enter and exit animations.
• Layout animations — size, position and shared-element transitions.
• Coming from Motion — every motion/react API and its Mercury equivalent.