Motion Plus Vue Components

Common errors

• Failed to resolve component: AnimateNumber

  cause The AnimateNumber component was not correctly imported or registered in your Vue application.
  fix Ensure you have `import { AnimateNumber } from 'motion-plus-vue'` in your script setup or component options, and that `motion-plus-vue` is correctly installed.

• Peer dependency 'motion-v@^2.0.0' not installed or not met

  cause The required peer dependency 'motion-v' at version 2.x is missing or an incompatible version is installed.
  fix Run `npm install motion-v@^2.0.0` or `yarn add motion-v@^2.0.0` to install the correct peer dependency.

• TypeError: Cannot read properties of undefined (reading 'install')

  cause Attempting to use `app.use()` with a non-plugin or an incorrectly imported plugin. The core `MotionPlugin` comes from `motion-v`, not `motion-plus-vue` directly.
  fix Ensure you are importing and using `MotionPlugin` correctly from `motion-v` if you intend to register global directives. Components from `motion-plus-vue` are typically imported and used directly in templates.

• TS2307: Cannot find module 'motion-plus-vue' or its corresponding type declarations.

  cause TypeScript compiler cannot locate the package or its type definitions, or the package is not installed.
  fix Ensure 'motion-plus-vue' is installed (`npm install motion-plus-vue`) and your `tsconfig.json` correctly includes `"allowSyntheticDefaultImports": true` and `"esModuleInterop": true` if you are using default imports, though named imports are preferred for this library.

Warnings

• breaking This package is strictly built for Vue 3. Using it with Vue 2.x will result in runtime errors due to fundamental API changes.
  Fix: Ensure your project uses Vue 3 (>=3.0.0). Upgrade your Vue project or find an alternative library compatible with Vue 2.
• breaking Requires 'motion-v' version 2.0.0 or higher as a peer dependency. Older versions of 'motion-v' will not provide the necessary APIs, leading to runtime failures.
  Fix: Install or upgrade 'motion-v' to a compatible version: `npm install motion-v@^2.0.0` or `yarn add motion-v@^2.0.0`.
• gotcha The `AnimateNumber` component, prominently featured by `motion-plus-vue`, is noted in `motion.dev` documentation as an 'exclusive to Motion+ members' feature. This may imply a requirement for a `motion-plus` package and a private token for installation or usage.
  Fix: Verify licensing requirements for `AnimateNumber` and any other 'Motion Plus' features you intend to use. You might need to purchase a Motion+ membership and install `motion-plus` with a private token.
• gotcha Animation libraries can sometimes cause issues with Server-Side Rendering (SSR) if not handled correctly. Ensure client-side-only animations are properly guarded (e.g., using `client-only` component in Nuxt or dynamic imports).
  Fix: Implement SSR-safe practices. For Nuxt, wrap components in `<client-only>`. For other SSR frameworks, use dynamic imports (`import('...')`) to load animation components only on the client.
• gotcha Performance can be impacted if complex animations are applied to a large number of elements or frequently updated. Monitor frame rates and optimize animations.
  Fix: Utilize performance optimization techniques: use CSS transforms where possible, debounce/throttle updates, and leverage Motion's performance features like 'willChange' properties.

Install

• npm install motion-plus-vue npm
• yarn add motion-plus-vue yarn
• pnpm add motion-plus-vue pnpm

Imports

• AnimateNumber
  wrong:

  import AnimateNumber from 'motion-plus-vue'

  correct:

  import { AnimateNumber } from 'motion-plus-vue'

  AnimateNumber is a named export for a Vue component, typically used directly in a Vue Single File Component (SFC).
• MotionPlugin
  wrong:

  import { MotionPlugin } from 'motion-plus-vue'

  correct:

  import { MotionPlugin } from 'motion-v'

  The global MotionPlugin for registering directives like `v-motion` comes from the core `motion-v` package, not `motion-plus-vue`. Install `motion-v` separately and import from it for global setup.
• v-motion
  wrong:

  import { vMotion } from 'motion-plus-vue'

  correct:

  import { vMotion } from 'motion-v'

  The `v-motion` directive for declarative animations is provided by the core `motion-v` package.

Quickstart

Shows a basic usage of the `<AnimateNumber>` component to display and animate a changing numeric value within a Vue 3 application.

<!-- App.vue -->
<script setup lang="ts">
import { ref } from 'vue';
// AnimateNumber is typically imported directly from motion-plus-vue
import { AnimateNumber } from 'motion-plus-vue';

const count = ref(0);

const increment = () => {
  count.value++;
};

const decrement = () => {
  if (count.value > 0) {
    count.value--;
  }
};
</script>

<template>
  <div class="container">
    <h1>Current Value: <AnimateNumber>{{ count }}</AnimateNumber></h1>
    <div class="controls">
      <button @click="increment">Increment</button>
      <button @click="decrement">Decrement</button>
    </div>
    <p>
      This example demonstrates the <code>&lt;AnimateNumber&gt;</code> component from <code>motion-plus-vue</code>.
      It animates the numeric value smoothly when the underlying `count` ref changes.
      The component internally leverages the <code>motion-v</code> animation engine for its effects.
    </p>
  </div>
</template>

<style scoped>
.container {
  font-family: sans-serif;
  text-align: center;
  padding: 20px;
  border: 1px solid #eee;
  border-radius: 8px;
  max-width: 400px;
  margin: 50px auto;
  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
}
h1 {
  margin-bottom: 20px;
  color: #333;
}
.controls button {
  background-color: #42b983;
  color: white;
  border: none;
  padding: 10px 20px;
  margin: 0 10px;
  border-radius: 5px;
  cursor: pointer;
  font-size: 16px;
  transition: background-color 0.3s ease;
}
.controls button:hover {
  background-color: #368d6f;
}
.controls button:active {
  background-color: #2b745a;
}
p {
  margin-top: 30px;
  font-size: 0.9em;
  color: #666;
  line-height: 1.5;
}
</style>