Skip to content

secondsky/claude-skills / plugins/motion/skills/motion

motion

Verified

Motion (Framer Motion) React animation library. Use for drag-and-drop, scroll animations, gestures, SVG morphing, or encountering bundle size, complex transitions, spring physics errors.

templates/layout-transitions.tsx

View on GitHub
// Motion Layout Animations & Shared Element Transitions
// Production-tested with Motion v12.43.0, React 19

/**
 * INSTALLATION
 *
 * pnpm add motion
 *
 * USAGE
 *
 * Copy components below into your project.
 * Layout animations use the FLIP technique for smooth, hardware-accelerated transitions.
 *
 * For Next.js App Router, add "use client" directive at top of file.
 */

import { motion, LayoutGroup } from "motion/react"
import { useState, ReactNode } from "react"

// ============================================================================
// PATTERN 1: Basic Layout Animation
// ============================================================================

/**
 * Automatically animates layout changes (position, size, etc.)
 * Uses FLIP technique: First, Last, Invert, Play
 */
export function ExpandableCard() {
  const [isExpanded, setIsExpanded] = useState(false)

  return (
    <motion.div
      layout // Enable FLIP layout animations
      onClick={() => setIsExpanded(!isExpanded)}
      className={`cursor-pointer bg-white border rounded-lg shadow-md p-6 ${
        isExpanded ? "w-full" : "w-64"
      }`}
      transition={{ layout: { duration: 0.3, type: "spring" } }}
    >
      <motion.h3 layout className="text-xl font-bold mb-2">
        Click to Expand
      </motion.h3>

      {isExpanded && (
        <motion.div
          initial={{ opacity: 0 }}
          animate={{ opacity: 1 }}
          transition={{ delay: 0.2 }}
        >
          <p>This content appears when expanded.</p>
          <p className="mt-2">Layout automatically animates the size change.</p>
        </motion.div>
      )}
    </motion.div>
  )
}

/**
 * KEY CONCEPT: The `layout` prop tells Motion to automatically animate
 * any layout changes (width, height, position) using GPU-accelerated transforms.
 * No JavaScript calculation needed - it's all done via FLIP technique.
 */

// ============================================================================
// PATTERN 2: Shared Element Transition (layoutId)
// ============================================================================

/**
 * Animate the same element between different states or routes.
 * Perfect for card → detail page transitions.
 */
interface Card {
  id: string
  title: string
  description: string
  color: string
}

export function SharedElementExample() {
  const [selectedCard, setSelectedCard] = useState<Card | null>(null)

  const cards: Card[] = [
    { id: "1", title: "Card 1", description: "Full description for card 1", color: "bg-red-500" },
    { id: "2", title: "Card 2", description: "Full description for card 2", color: "bg-blue-500" },
    { id: "3", title: "Card 3", description: "Full description for card 3", color: "bg-green-500" },
  ]

  return (
    <div>
      {/* Grid view */}
      {!selectedCard && (
        <div className="grid grid-cols-3 gap-4">
          {cards.map((card) => (
            <motion.div
              key={card.id}
              layoutId={card.id} // Connect this element to detail view
              onClick={() => setSelectedCard(card)}
              className={`${card.color} text-white p-6 rounded-lg cursor-pointer h-32 flex items-center justify-center`}
            >
              <motion.h3 layoutId={`title-${card.id}`} className="text-xl font-bold">
                {card.title}
              </motion.h3>
            </motion.div>
          ))}
        </div>
      )}

      {/* Detail view */}
      {selectedCard && (
        <motion.div
          layoutId={selectedCard.id} // Same layoutId = smooth transition
          onClick={() => setSelectedCard(null)}
          className={`${selectedCard.color} text-white p-12 rounded-lg cursor-pointer`}
        >
          <motion.h3 layoutId={`title-${selectedCard.id}`} className="text-4xl font-bold mb-4">
            {selectedCard.title}
          </motion.h3>
          <motion.p
            initial={{ opacity: 0 }}
            animate={{ opacity: 1 }}
            transition={{ delay: 0.2 }}
            className="text-xl"
          >
            {selectedCard.description}
          </motion.p>
        </motion.div>
      )}
    </div>
  )
}

/**
 * KEY CONCEPT: Elements with the same `layoutId` are treated as the same element
 * across different states/routes. Motion automatically morphs between them.
 */

// ============================================================================
// PATTERN 3: List Reordering with Layout
// ============================================================================

/**
 * Automatically animate items when list order changes.
 * Perfect for drag-to-reorder, filtering, sorting.
 */
interface Item {
  id: number
  text: string
}

export function AnimatedList() {
  const [items, setItems] = useState<Item[]>([
    { id: 1, text: "Item 1" },
    { id: 2, text: "Item 2" },
    { id: 3, text: "Item 3" },
    { id: 4, text: "Item 4" },
  ])

  const shuffle = () => {
    setItems([...items].sort(() => Math.random() - 0.5))
  }

  const reverse = () => {
    setItems([...items].reverse())
  }

  return (
    <div>
      <div className="flex gap-2 mb-4">
        <button onClick={shuffle} className="px-4 py-2 bg-blue-600 text-white rounded">
          Shuffle
        </button>
        <button onClick={reverse} className="px-4 py-2 bg-purple-600 text-white rounded">
          Reverse
        </button>
      </div>

      <div className="space-y-2">
        {items.map((item) => (
          <motion.div
            key={item.id}
            layout // Animate position changes automatically
            className="p-4 bg-white border rounded-lg shadow-sm"
            transition={{ type: "spring", stiffness: 300, damping: 30 }}
          >
            {item.text}
          </motion.div>
        ))}
      </div>
    </div>
  )
}

/**
 * KEY CONCEPT: When items reorder, the `layout` prop automatically animates
 * each item to its new position. No manual position calculation needed.
 */

// ============================================================================
// PATTERN 4: LayoutGroup (Namespacing)
// ============================================================================

/**
 * Use LayoutGroup to namespace layoutIds for reusable components.
 * Prevents conflicts when using multiple instances.
 */
interface TabPanelProps {
  tabs: Array<{ id: string; label: string; content: ReactNode }>
}

export function TabPanel({ tabs }: TabPanelProps) {
  const [activeTab, setActiveTab] = useState(tabs[0].id)

  return (
    <LayoutGroup> {/* Namespace layoutIds within this group */}
      <div className="space-y-4">
        {/* Tab buttons */}
        <div className="flex gap-4 border-b border-gray-200">
          {tabs.map((tab) => (
            <button
              key={tab.id}
              onClick={() => setActiveTab(tab.id)}
              className="relative px-4 py-2"
            >
              {tab.label}

              {/* Shared underline */}
              {activeTab === tab.id && (
                <motion.div
                  layoutId="underline" // Shared within LayoutGroup
                  className="absolute bottom-0 left-0 right-0 h-0.5 bg-blue-600"
                  transition={{ type: "spring", stiffness: 300, damping: 30 }}
                />
              )}
            </button>
          ))}
        </div>

        {/* Tab content */}
        <div className="p-4">
          {tabs.find((tab) => tab.id === activeTab)?.content}
        </div>
      </div>
    </LayoutGroup>
  )
}

/**
 * USAGE
 *
 * <div className="grid grid-cols-2 gap-4">
 *   <TabPanel tabs={[...]} />
 *   <TabPanel tabs={[...]} />  (No layoutId conflicts!)
 * </div>
 */

// ============================================================================
// PATTERN 5: Scrollable Container (layoutScroll)
// ============================================================================

/**
 * Fix layout animations in scrollable containers.
 * Without layoutScroll, animations break when container is scrolled.
 */
export function ScrollableList() {
  const [items, setItems] = useState<Item[]>(
    Array.from({ length: 20 }, (_, i) => ({
      id: i + 1,
      text: `Item ${i + 1}`,
    }))
  )

  const removeItem = (id: number) => {
    setItems(items.filter((item) => item.id !== id))
  }

  return (
    <motion.div
      layoutScroll // CRITICAL: Fixes animations in scrolled containers
      className="h-96 overflow-auto border border-gray-200 rounded-lg p-4 space-y-2"
    >
      {items.map((item) => (
        <motion.div
          key={item.id}
          layout
          initial={{ opacity: 0, scale: 0.8 }}
          animate={{ opacity: 1, scale: 1 }}
          exit={{ opacity: 0, scale: 0.8 }}
          className="p-4 bg-white border rounded-lg shadow-sm flex justify-between items-center"
        >
          <span>{item.text}</span>
          <button
            onClick={() => removeItem(item.id)}
            className="px-3 py-1 bg-red-500 text-white rounded text-sm"
          >
            Remove
          </button>
        </motion.div>
      ))}
    </motion.div>
  )
}

/**
 * KEY CONCEPT: Without `layoutScroll`, removing items from a scrolled container
 * causes incomplete/broken animations. layoutScroll fixes this by accounting
 * for scroll offset in FLIP calculations.
 */

// ============================================================================
// PATTERN 6: Fixed Position (layoutRoot)
// ============================================================================

/**
 * Fix layout animations in fixed-position elements.
 * Without layoutRoot, fixed elements animate incorrectly.
 */
export function FixedModal() {
  const [isOpen, setIsOpen] = useState(false)

  return (
    <>
      <button
        onClick={() => setIsOpen(!isOpen)}
        className="px-4 py-2 bg-blue-600 text-white rounded"
      >
        Toggle Fixed Modal
      </button>

      {isOpen && (
        <motion.div
          layoutRoot // CRITICAL: Fixes animations in fixed elements
          layout
          className="fixed bottom-4 right-4 w-64 bg-white border rounded-lg shadow-2xl p-4 z-50"
        >
          <h3 className="font-bold mb-2">Fixed Modal</h3>
          <p className="text-sm text-gray-700">
            This is a fixed-position element with layout animations.
          </p>
        </motion.div>
      )}
    </>
  )
}

/**
 * KEY CONCEPT: Fixed-position elements need `layoutRoot` to correctly
 * calculate scroll offset during FLIP animations.
 */

// ============================================================================
// PATTERN 7: Grid → List View Switching
// ============================================================================

/**
 * Smooth transition between grid and list layouts.
 */
export function ViewSwitcher() {
  const [view, setView] = useState<"grid" | "list">("grid")

  const items = Array.from({ length: 9 }, (_, i) => ({
    id: i + 1,
    title: `Item ${i + 1}`,
  }))

  return (
    <div>
      <div className="flex gap-2 mb-4">
        <button
          onClick={() => setView("grid")}
          className={`px-4 py-2 rounded ${
            view === "grid" ? "bg-blue-600 text-white" : "bg-gray-200"
          }`}
        >
          Grid
        </button>
        <button
          onClick={() => setView("list")}
          className={`px-4 py-2 rounded ${
            view === "list" ? "bg-blue-600 text-white" : "bg-gray-200"
          }`}
        >
          List
        </button>
      </div>

      <motion.div
        layout
        className={view === "grid" ? "grid grid-cols-3 gap-4" : "space-y-2"}
      >
        {items.map((item) => (
          <motion.div
            key={item.id}
            layout
            className="p-6 bg-white border rounded-lg shadow-sm"
            transition={{ type: "spring", stiffness: 300, damping: 30 }}
          >
            <h3 className="font-bold">{item.title}</h3>
          </motion.div>
        ))}
      </motion.div>
    </div>
  )
}

// ============================================================================
// PATTERN 8: Drag to Reorder (Manual Implementation)
// ============================================================================

/**
 * Drag items to reorder with visual feedback.
 * Note: Motion's Reorder component has Next.js compatibility issues.
 * This is a manual implementation that works everywhere.
 */
export function DragToReorder() {
  const [items, setItems] = useState<Item[]>([
    { id: 1, text: "Drag me" },
    { id: 2, text: "Reorder me" },
    { id: 3, text: "Move me around" },
    { id: 4, text: "Drop me anywhere" },
  ])

  return (
    <div className="space-y-2">
      {items.map((item, index) => (
        <motion.div
          key={item.id}
          layout
          drag="y"
          dragConstraints={{ top: 0, bottom: 0 }}
          dragElastic={0.1}
          whileDrag={{ scale: 1.05, boxShadow: "0 10px 40px rgba(0,0,0,0.2)" }}
          className="p-4 bg-white border rounded-lg shadow-sm cursor-grab active:cursor-grabbing"
          transition={{ type: "spring", stiffness: 300, damping: 30 }}
        >
          <div className="flex items-center gap-3">
            <span className="text-gray-400">☰</span>
            <span>{item.text}</span>
          </div>
        </motion.div>
      ))}
    </div>
  )
}

/**
 * Note: Full drag-to-reorder with position updates requires tracking
 * drag position and updating array order. For production, consider:
 * - @dnd-kit/core (recommended for Next.js)
 * - react-beautiful-dnd
 * - Motion's Reorder component (has Next.js issues, see GitHub #2183)
 */

// ============================================================================
// PATTERN 9: Masonry Layout Animation
// ============================================================================

/**
 * Animate items in masonry/Pinterest-style layout.
 */
export function MasonryLayout() {
  const [items, setItems] = useState(
    Array.from({ length: 12 }, (_, i) => ({
      id: i + 1,
      height: Math.floor(Math.random() * 200) + 100,
    }))
  )

  const shuffle = () => {
    setItems([...items].sort(() => Math.random() - 0.5))
  }

  return (
    <div>
      <button onClick={shuffle} className="px-4 py-2 bg-blue-600 text-white rounded mb-4">
        Shuffle
      </button>

      <div className="columns-3 gap-4">
        {items.map((item) => (
          <motion.div
            key={item.id}
            layout
            className="mb-4 bg-gradient-to-br from-purple-500 to-pink-500 rounded-lg p-4 text-white font-bold break-inside-avoid"
            style={{ height: item.height }}
            transition={{ type: "spring", stiffness: 300, damping: 30 }}
          >
            Item {item.id}
          </motion.div>
        ))}
      </div>
    </div>
  )
}

// ============================================================================
// ALL EXAMPLES DEMO
// ============================================================================

export function LayoutAnimationsDemo() {
  return (
    <div className="max-w-4xl mx-auto p-8 space-y-12">
      <h1 className="text-4xl font-bold mb-8">Layout Animations & Shared Elements</h1>

      <section>
        <h2 className="text-2xl font-bold mb-4">1. Basic Layout Animation</h2>
        <ExpandableCard />
      </section>

      <section>
        <h2 className="text-2xl font-bold mb-4">2. Shared Element Transition</h2>
        <SharedElementExample />
      </section>

      <section>
        <h2 className="text-2xl font-bold mb-4">3. List Reordering</h2>
        <AnimatedList />
      </section>

      <section>
        <h2 className="text-2xl font-bold mb-4">4. Tab Panel with LayoutGroup</h2>
        <TabPanel
          tabs={[
            { id: "1", label: "Tab 1", content: <p>Content for tab 1</p> },
            { id: "2", label: "Tab 2", content: <p>Content for tab 2</p> },
            { id: "3", label: "Tab 3", content: <p>Content for tab 3</p> },
          ]}
        />
      </section>

      <section>
        <h2 className="text-2xl font-bold mb-4">5. Scrollable Container</h2>
        <ScrollableList />
      </section>

      <section>
        <h2 className="text-2xl font-bold mb-4">6. Fixed Position Modal</h2>
        <FixedModal />
      </section>

      <section>
        <h2 className="text-2xl font-bold mb-4">7. Grid/List View Switcher</h2>
        <ViewSwitcher />
      </section>

      <section>
        <h2 className="text-2xl font-bold mb-4">8. Drag to Reorder</h2>
        <DragToReorder />
      </section>

      <section>
        <h2 className="text-2xl font-bold mb-4">9. Masonry Layout</h2>
        <MasonryLayout />
      </section>
    </div>
  )
}

/**
 * PERFORMANCE TIPS
 *
 * 1. Add willChange for layout animations:
 *    <motion.div layout style={{ willChange: "transform" }} />
 *
 * 2. Use layout prop only when needed:
 *    - If element size/position doesn't change, don't use layout
 *
 * 3. Combine with AnimatePresence for enter/exit:
 *    <AnimatePresence>
 *      {items.map(item => (
 *        <motion.div key={item.id} layout exit={{ opacity: 0 }} />
 *      ))}
 *    </AnimatePresence>
 *
 * 4. Use LayoutGroup to isolate layout calculations:
 *    - Prevents unnecessary recalculations across unrelated components
 *
 * See ../references/performance-optimization.md for full guide
 */

/**
 * COMMON ISSUES
 *
 * 1. Broken animations in scrollable containers
 *    Solution: Add layoutScroll prop
 *
 * 2. Incorrect animations in fixed elements
 *    Solution: Add layoutRoot prop
 *
 * 3. layoutId conflicts in reusable components
 *    Solution: Wrap in LayoutGroup
 *
 * 4. Elements not unmounting with layoutId + AnimatePresence
 *    Solution: Use LayoutGroup or avoid mixing exit + layout animations
 *
 * See ../SKILL.md for full troubleshooting guide
 */

/**
 * NEXT.JS USAGE
 *
 * Add "use client" directive at top of file:
 *
 * "use client"
 *
 * import { motion, LayoutGroup } from "motion/react-client"
 *
 * See ../references/nextjs-integration.md for comprehensive guide
 */
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall