Install Motion UI

Adapt with AI

Every Motion UI section and component comes with an Adapt with AI button. Clicking that copies a prompt for you to drop directly into your agent, which will adapt the design but preserve the animation. The prompt includes a starter motion.theme.ts, and tells the agent to add it only when your project does not already have one.

Alternatively, install the Motion AI Kit to let your agent search and install Motion UI components directly.

Install with the shadcn CLI

Motion UI components are built with shadcn tokens, meaning if you already have a customised shadcn design, you can drop Motion UI in directly from your CLI.

1. Add the @motion registry to your project’s components.json (create one first with npx shadcn init if you don’t have one yet).

   components.jsonCopyCopiedCopy

   {
     "registries": {
       "@motion": {
         "url": "https://api.motion.dev/ui/registry/{name}.json",
         "headers": {
           "Authorization": "Bearer ${MOTION_TOKEN}"
         }
       }
     }
   }

2. Generate a token.

   export MOTION_TOKEN=your-token-hereCopyCopiedCopy

3. Wire the private npm registry with a .npmrc in your project root, using the same token. Many Motion UI sections use Motion+ exclusive components like Carousel and AnimateNumber. Adding this allows npm to install the Motion+ library. See the Motion+ installation guide for full npm, Yarn and Bun setup instructions.

   .npmrcCopyCopiedCopy

   @motionplus:registry=https://api.motion.dev/npm/
   //api.motion.dev/npm/:_authToken=${MOTION_TOKEN}

4. If your project does not already have a motion.theme.ts, install the starter theme once. This is your project’s motion configuration, so do not rerun this command after customising the file.

   npx shadcn@latest add @motion/motion-themeCopyCopiedCopy

5. Add any section or component via the copy/paste command on its product page.

   npx shadcn@latest add @motion/hero-parallax-layersCopyCopiedCopy

Update your motion theme

motion.theme.ts is project-owned. Open it and change only the tokens you want to tune. defineTheme merges your partial configuration over Motion UI’s defaults, so you do not need to copy the complete starter theme into every edit.

import { defineTheme } from "@/components/motion-ui/ui-theme"

export default defineTheme({
  transitions: {
    ui: { stiffness: 250, damping: 28 },
    gentle: { stiffness: 90, damping: 18 },
  },
  stagger: { base: 0.1 },
  travel: { enter: 32, section: 64 },
  inView: { amount: 0.35, once: true },
  reducedMotion: "calm",
})

• Transitions are named by purpose: snap for immediate feedback, ui for common controls and reveals, gentle for large surfaces, lively for celebratory motion and ambient for repeating background effects. Higher stiffness accelerates the spring; higher damping removes bounce.

• Stagger values are delays between children in seconds. Travel values are distances in pixels. In view controls how much of a section must be visible and whether its entrance runs only once.

• Set reducedMotion to "calm" to remove travel while keeping opacity fades, or "off" to disable animation when the visitor prefers reduced motion.

Mount the provider once around your app root so every installed section reads the same file. Adjust the import path if your theme lives somewhere other than the configured @ alias.

import {
  MotionUIThemeProvider,
} from "@/components/motion-ui/ui-theme"
import motionTheme from "@/motion.theme"

export function App({ children }) {
  return (
    <MotionUIThemeProvider theme={motionTheme}>
      {children}
    </MotionUIThemeProvider>
  )
}

Save the file to retune every Motion UI section that uses those tokens. Component and section update commands do not overwrite motion.theme.ts; only rerunning the dedicated theme install command can replace it.

Install troubleshooting