playbooks

home / skills / onmax / nuxt-skills / motion

motion skill

/skills/motion

This skill helps you implement Motion Vue animations in Vue 3 and Nuxt with motion component usage, gestures, and scroll effects.

npx playbooks add skill onmax/nuxt-skills --skill motion

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
3.1 KB
---
name: motion
description: Use when adding animations with Motion Vue (motion-v) - provides motion component API, gesture animations, scroll-linked effects, layout transitions, and composables for Vue 3/Nuxt
license: MIT
---

# Motion Vue (motion-v)

Animation library for Vue 3 and Nuxt. Production-ready, hardware-accelerated animations with minimal bundle size.

**Current stable:** motion-v 1.x - Vue port of Motion (formerly Framer Motion)

## Overview

Progressive reference for Motion Vue animations. Load only files relevant to current task (~200 tokens base, 500-1500 per sub-file).

## When to Use

**Use Motion Vue for:**

- Simple declarative animations (fade, slide, scale)
- Gesture-based interactions (hover, tap, drag)
- Scroll-linked animations
- Layout animations and shared element transitions
- Spring physics animations

**Consider alternatives:**

- **GSAP** - Complex timelines, SVG morphing, scroll-triggered sequences
- **@vueuse/motion** - Simpler API, less features, smaller bundle
- **CSS animations** - Simple transitions without JS

## Installation

```bash
# Vue 3
pnpm add motion-v

# Nuxt 3
pnpm add motion-v @vueuse/nuxt
```

```ts
// nuxt.config.ts - Nuxt 3 setup
export default defineNuxtConfig({
  modules: ['motion-v/nuxt'],
})
```

## Quick Reference

| Working on...                | Load file                 |
| ---------------------------- | ------------------------- |
| Motion component, gestures   | references/components.md  |
| useMotionValue, useScroll    | references/composables.md |
| Animation examples, patterns | references/examples.md    |

## Loading Files

**Load one file at a time based on context:**

- Component animations → [references/components.md](references/components.md)
- Composables, motion values → [references/composables.md](references/composables.md)
- Examples, inspiration → [references/examples.md](references/examples.md)

## Core Concepts

### Motion Component

Render any HTML/SVG element with animation capabilities:

```vue
<script setup lang="ts">
import { Motion } from 'motion-v'
</script>

<template>
  <Motion.div
    :initial="{ opacity: 0, y: 20 }"
    :animate="{ opacity: 1, y: 0 }"
    :exit="{ opacity: 0, y: -20 }"
    :transition="{ duration: 0.3 }"
  >
    Animated content
  </Motion.div>
</template>
```

### Gesture Animations

```vue
<Motion.button
  :whileHover="{ scale: 1.05 }"
  :whilePress="{ scale: 0.95 }"
  :transition="{ type: 'spring', stiffness: 400 }"
>
  Click me
</Motion.button>
```

### Scroll Animations

```vue
<Motion.div
  :initial="{ opacity: 0 }"
  :whileInView="{ opacity: 1 }"
  :viewport="{ once: true, margin: '-100px' }"
>
  Appears on scroll
</Motion.div>
```

## Available Guidance

**[references/components.md](references/components.md)** - Motion component variants, animation props, gesture props, layout animations, transition configuration

**[references/composables.md](references/composables.md)** - useMotionValue, useSpring, useTransform, useScroll, useInView, animate()

**[references/examples.md](references/examples.md)** - External resources, component libraries, animation patterns and inspiration

Overview

This skill provides a focused guide for adding animations with Motion Vue (motion-v) in Vue 3 and Nuxt projects. It highlights the motion component API, gesture animations, scroll-linked effects, layout transitions, and key composables to build hardware-accelerated, production-ready animations with a small bundle footprint.

How this skill works

The skill explains how to use Motion components to wrap HTML/SVG elements and declare initial, animate, and exit states with transition options. It also covers gesture props (hover, press, drag), scroll- and viewport-linked triggers, and composables (useMotionValue, useSpring, useScroll, useInView, animate) for programmatic control and value transforms.

When to use it

  • Add simple declarative animations like fade, slide, and scale to UI elements.
  • Create gesture-driven interactions (hover, tap/press, drag) with spring physics.
  • Animate elements when they enter the viewport or link animations to scroll position.
  • Implement layout transitions and shared element animations between routes or components.
  • Prefer Motion Vue when you need hardware-accelerated, production-ready animations with minimal bundle size.

Best practices

  • Use Motion components for element-scoped animations and composables for cross-component value control.
  • Keep transitions lightweight: prefer spring settings for natural motion and short durations for UI feedback.
  • Use viewport options (once, margin) to avoid repeated animations and improve performance.
  • Combine useMotionValue and useTransform to drive complex, scroll-linked effects without heavy JavaScript loops.
  • Consider fallback to CSS for ultra-simple transitions to avoid unnecessary JS overhead.

Example use cases

  • Fade and slide a card list into view with :initial and :whileInView for progressive reveal.
  • Add whileHover and whilePress to buttons for tactile micro-interactions using spring transitions.
  • Link header style or parallax effects to page scroll with useScroll and useTransform.
  • Animate shared elements between pages using layout transitions for smooth route changes.
  • Create draggable UI panels with drag gestures and physics-based motion for natural interaction.

FAQ

Is Motion Vue appropriate for production?

Yes. Motion Vue is production-ready and optimized for hardware-accelerated animations with a small bundle size.

When should I use composables vs Motion components?

Use Motion components for element-level declarative animations. Use composables when you need programmatic control, cross-component syncing, or scroll-linked value transforms.