Star203

Documentation

Installation

Install Motionwind v2 in Next.js, React/Vite, Vue/Nuxt, vanilla JavaScript, or React Native/Expo.

Installation

Motionwind supports all major web frameworks. The CLI auto-detects your setup and installs the right packages.

Quick install

npx create-motionwind@2 init

This command:

  1. Detects your framework (Next.js, React, Vue, Nuxt, vanilla, Expo).
  2. Detects your package manager (npm, pnpm, Yarn, Bun).
  3. Installs the adapter package and its dependencies.
  4. Creates motionwind.config.ts with sensible defaults.
  5. Modifies your build config (Vite, Next.js, etc.) if it can do so safely.

Preview what it would do without writing anything:

npx create-motionwind@2 init --dry-run

Explicit framework targets

If auto-detection fails or you want to be explicit:

npx create-motionwind@2 init --framework=next
npx create-motionwind@2 init --framework=react
npx create-motionwind@2 init --framework=vue
npx create-motionwind@2 init --framework=vanilla
npx create-motionwind@2 init --framework=react-native

Manual installation

If you prefer to install packages yourself:

React, Next.js, React + Vite

npm install motionwind-react@2 motion motionwind-core@2

Vue, Nuxt, Vue + Vite

npm install motionwind-vue@2 motion-v @vueuse/core motionwind-core@2

Vanilla JavaScript

npm install motionwind-vanilla@2 motion motionwind-core@2

React Native, Expo

npm install motionwind-react-native@2 react-native-reanimated react-native-gesture-handler nativewind motionwind-core@2

Framework integrations

After installing packages, add the build integration for your framework.

Next.js

// next.config.mjs
import { withMotionwind } from "motionwind-react/next";
import motionwindConfig from "./motionwind.config";

export default withMotionwind({}, motionwindConfig);

What withMotionwind does:

  • Adds a webpack rule that runs the motionwind Babel plugin before SWC.
  • Transforms animate-* classes in .tsx and .jsx files.
  • Adds "use client" and import { motion } from "motion/react" automatically.
  • Preserves your existing webpack config.

React + Vite

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import motionwind from "motionwind-react/vite";
import motionwindConfig from "./motionwind.config";

export default defineConfig({
  plugins: [motionwind(motionwindConfig), react()],
});

The plugin runs before @vitejs/plugin-react. It skips files that don't contain animate- for fast builds.

Vue + Vite

// vite.config.ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import {
  createMotionwindTransform,
  MotionwindPlugin,
} from "motionwind-vue/vite";
import motionwindConfig from "./motionwind.config";

export default defineConfig({
  plugins: [
    createMotionwindTransform(motionwindConfig),
    vue(),
    MotionwindPlugin(motionwindConfig),
  ],
});

Vue needs both the template transform and the plugin.

Nuxt

Add the Nuxt module (the CLI does this automatically):

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ["motionwind-vue/nuxt"],
});

Use the <Motionwind> component or useMotionwind() composable for dynamic class bindings.

Vanilla JavaScript

import { motionwind } from "motionwind-vanilla";
import motionwindConfig from "./motionwind.config";

motionwind({ config: motionwindConfig });

The vanilla runtime parses animate-* classes in the DOM and applies Motion animations directly.

React Native, Expo

import { MotionwindProvider } from "motionwind-react-native";
import motionwindConfig from "./motionwind.config";

export default function App() {
  return (
    <MotionwindProvider config={motionwindConfig}>
      <YourApp />
    </MotionwindProvider>
  );
}

React Native uses mw.* runtime components backed by Reanimated.

Verify the setup

Run the diagnostic:

npx create-motionwind@2 doctor

Test with a simple element:

Web:

<button
  class="animate-hover:scale-110 animate-tap:scale-90 animate-focus:scale-105 animate-spring"
>
  Test Motionwind
</button>

React Native:

import { mw } from "motionwind-react-native";

<mw.Pressable className="animate-tap:scale-90 animate-spring">
  <mw.Text>Test Motionwind</mw.Text>
</mw.Pressable>;

Troubleshooting

ProblemCauseFix
Animations don't playBuild integration not addedRun npx create-motionwind@2 doctor to check
ReferenceError: motion is not definedMissing Motion dependencyRun npm install motion (or motion-v for Vue)
Unknown class warningsTypo or missing tokenCheck spelling; run npx create-motionwind@2 doctor
React Native: animations crashReanimated Babel plugin missingEnable Reanimated in babel.config.js and clear Metro cache
Vite plugin errorPlugin order wrongmotionwind plugin must come before the React plugin
Dynamic classes not animatingUsing regular <button> instead of mw.buttonUse mw.* for dynamic class names

Tailwind CSS is optional

Motionwind's animate-* parser works independently of Tailwind CSS. The non-animation classes in your className pass through unchanged. You can use Motionwind with any CSS approach: Tailwind, CSS Modules, styled-components, or plain CSS.

Next steps