Motion System v4.2
Produktionsreifes UI-Bewegungssystem für React / Next.js.
Fokussiert auf Performance, Barrierefreiheit und Benutzerfreundlichkeit – nicht auf Dekoration.
Wann verwenden
Verwenden Sie dieses Bewegungssystem, wenn Bewegung:
- Aufmerksamkeit lenkt (z.B. Onboarding, wichtige Aktionen)
- Zustand kommuniziert (Laden, Erfolg, Fehler, Übergänge)
- Räumliche Kontinuität bewahrt (Layout-Änderungen, Navigation)
Geeignete Szenarien
- Interaktive Komponenten (Buttons, Modale, Menüs)
- Zustandsübergänge (Laden → geladen, offen → geschlossen)
- Navigation und Layout-Kontinuität (gemeinsame Elemente, Überblendung)
Überlegungen
- Barrierefreiheit: Immer reduzierte Bewegung unterstützen
- Geräteanpassung: Für schwächere Geräte anpassen
- Performance-Abwägungen: Bevorzugen Sie Reaktionsfähigkeit vor visueller Glätte
Bewegung vermeiden, wenn
- Sie rein dekorativ ist
- Sie die Benutzerfreundlichkeit oder Klarheit beeinträchtigt
- Sie die Performance negativ beeinflusst
Funktionsweise
Kernprinzip
Bewegung muss:
- Aufmerksamkeit lenken
- Zustand kommunizieren
- Räumliche Kontinuität bewahren
Wenn keins zutrifft → entfernen.
Installation
npm install motion
Version
motion/react- Standard für aktuelle Motion für React-Projekte (Paket:motion)framer-motion- Legacy-Import-Pfad für Projekte, die noch von Framer Motion abhängen
Nicht mischen. Mischen führt zu widersprüchlichen internen Schedulern und defekten AnimatePresence-Kontexten – Komponenten aus einem Paket koordinieren Exit-Animationen nicht mit Komponenten aus dem anderen.
Um zu prüfen, welche Version Ihr Projekt verwendet:
cat package.json | grep -E '"motion"|"framer-motion"'
Immer aus einer Quelle konsistent importieren:
// Richtig (modern)
import { motion, AnimatePresence } from "motion/react"
// Richtig (Legacy)
import { motion, AnimatePresence } from "framer-motion"
// Niemals beide im selben Projekt mischen
Motion-Tokens
// motionTokens.ts
export const motionTokens = {
duration: {
fast: 0.18,
normal: 0.35,
slow: 0.6
},
// Verwenden Sie diese als `ease`-Wert innerhalb eines `transition`-Objekts:
// transition={{ duration: motionTokens.duration.normal, ease: motionTokens.easing.smooth }}
easing: {
smooth: [0.22, 1, 0.36, 1] as [number, number, number, number],
sharp: [0.4, 0, 0.2, 1] as [number, number, number, number]
},
distance: {
sm: 8,
md: 16,
lg: 24
}
}
Anwendungsbeispiel:
import { motionTokens } from "@/lib/motionTokens"
<motion.div
initial={{ opacity: 0, y: motionTokens.distance.md }}
animate={{ opacity: 1, y: 0 }}
transition={{
duration: motionTokens.duration.normal,
ease: motionTokens.easing.smooth
}}
/>
Performance-Regeln
Sicher
- transform
- opacity
Vermeiden
- width / height
- top / left
Regel: Reaktionsfähigkeit > Glätte
Geräteanpassung
Die Heuristik kombiniert die Anzahl der CPU-Kerne und den verfügbaren Arbeitsspeicher für ein zuverlässigeres Signal. deviceMemory ist auf Chrome/Android verfügbar; der Fallback deckt Safari und Firefox ab.
const isLowEnd =
typeof navigator !== "undefined" && (
// Wenig Arbeitsspeicher (nur Chrome/Android; sonst undefined → als leistungsfähig behandeln)
(navigator.deviceMemory !== undefined && navigator.deviceMemory <= 2) ||
// Wenige Kerne UND keine Memory-API (deckt Safari/Firefox auf schwacher Hardware ab)
(navigator.deviceMemory === undefined && navigator.hardwareConcurrency <= 4)
)
const duration = isLowEnd ? 0.2 : 0.4
Barrierefreiheit
JS (useReducedMotion)
import { motion, useReducedMotion } from "motion/react"
export function FadeIn() {
const reduce = useReducedMotion()
return (
<motion.div
initial={{ opacity: 0, y: reduce ? 0 : 24 }}
animate={{ opacity: 1, y: 0 }}
/>
)
}
CSS
@media (prefers-reduced-motion: reduce) {
.motion-safe-transition {
transition: opacity 0.2s;
}
.motion-reduce-transform {
transform: none !important;
}
}
Tailwind
<div class="motion-safe:animate-fade motion-reduce:opacity-100"></div>
Architektur & Muster
Kernmuster
| Szenario | Muster |
|---|---|
| Hover-Feedback | whileHover |
| Tipp-/Drück-Feedback | whileTap |
| Einblenden beim Scrollen | whileInView |
| Scroll-gebundener Wert | useScroll + useTransform |
| Bedingtes Ein-/Ausblenden | AnimatePresence |
| Kleine Layout-Änderungen (einzelnes Element, < ~300px Änderung) | layout-Prop |
| Große Layout-Änderungen oder seitenweite Reflows | layout vermeiden; CSS-Übergänge oder Routing auf Seitenebene verwenden |
| Komplexe, imperative Sequenzen | useAnimate |
Warum
layoutbei großen Containern vermeiden? Die Layout-Animation von Framer verwendettransform, um Positionen abzugleichen, aber bei Elementen, die das gesamte Viewport einnehmen oder tiefe Reflows auslösen, verursachen die Messkosten sichtbares Ruckeln und CLS. Bevorzugen Sie CSS Grid/Flexbox-Übergänge oder koordinieren Sie mitlayoutIdnur auf bestimmten Kindelementen.
Layout & Übergänge
- Shared-Element-Übergänge →
layoutId(muss pro eingehängter Instanz eindeutig sein) - Enter-/Exit-Übergänge →
AnimatePresence(siehemode-Hinweise unten)
AnimatePresence mode
Geben Sie immer explizit mode an – die Voreinstellung ("sync") führt Enter und Exit gleichzeitig aus, was bei den meisten UI-Mustern zu visuellen Überlappungen führt.
mode | Wann verwenden |
|---|---|
"wait" | Exit wird abgeschlossen, bevor Enter startet. Verwenden für Modale, Toasts, Seitenübergänge. |
"sync" (Standard) | Enter und Exit überlappen sich. Nur verwenden, wenn Überlappung beabsichtigt ist (z.B. Crossfade-Karussells). |
"popLayout" | Das ausgehende Element wird sofort aus dem Layoutfluss entfernt; verbleibende Elemente animieren zum Auffüllen. Verwenden für Listen, Tabs, ausblendbare Karten. |
// Modal – immer "wait" verwenden
<AnimatePresence mode="wait">
{open && <Modal key="modal" />}
</AnimatePresence>
// Ausblendbares Listenelement – "popLayout" verwenden
<AnimatePresence mode="popLayout">
{items.map(item => <Card key={item.id} />)}
</AnimatePresence>
Fortgeschrittene Muster (Konzepte)
- Parallax (scroll-gebundene Transformationen)
- Scroll Storytelling (klebrige Abschnitte)
- 3D-Kippen (zeigerbasierte Transformationen)
- Crossfade (geteiltes
layoutId) - Progressives Einblenden (clip-path)
- Skeleton-Laden (wiederholte Opazität)
- Mikro-Interaktionen (Hover/Tap-Feedback)
- Feder-System (physikbasierte Bewegung)
Modale – Grundlagen
- Fokusfalle
- Escape-Schließen
- Scroll-Sperre
- ARIA-Rollen
AnimatePresence mode="wait"verwenden, damit die Exit-Animation abgeschlossen ist, bevor das nächste Modal eintritt
Vollständiges Beispiel
import React, { useEffect, useRef, useState } from "react"
import { motion, AnimatePresence } from "motion/react"
function useFocusTrap(ref: React.RefObject<HTMLDivElement | null>, active: boolean) {
useEffect(() => {
if (!active || !ref.current) return
const el = ref.current
const focusable = el.querySelectorAll<HTMLElement>(
'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
)
const first = focusable[0]
const last = focusable[focusable.length - 1]
function handleKey(e: KeyboardEvent) {
if (e.key !== "Tab") return
if (e.shiftKey && document.activeElement === first) {
e.preventDefault()
last?.focus()
} else if (!e.shiftKey && document.activeElement === last) {
e.preventDefault()
first?.focus()
}
}
el.addEventListener("keydown", handleKey)
first?.focus()
return () => el.removeEventListener("keydown", handleKey)
}, [active, ref])
}
function useScrollLock(active: boolean) {
useEffect(() => {
if (!active) return
const prev = document.body.style.overflow
document.body.style.overflow = "hidden"
return () => { document.body.style.overflow = prev }
}, [active])
}
function Modal({ open, closeModal }: { open: boolean; closeModal: () => void }) {
const ref = useRef<HTMLDivElement>(null)
useFocusTrap(ref, open)
useScrollLock(open)
useEffect(() => {
function onKey(e: KeyboardEvent) {
if (e.key === "Escape") closeModal()
}
if (open) window.addEventListener("keydown", onKey)
return () => window.removeEventListener("keydown", onKey)
}, [open, closeModal])
return (
// mode="wait" stellt sicher, dass die Exit-Animation abgeschlossen ist, bevor ein neues Modal eintritt
<AnimatePresence mode="wait">
{open && (
<motion.div
role="dialog"
aria-modal="true"
aria-labelledby="modal-title"
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0 }}
transition={{ duration: 0.2 }}
className="fixed inset-0 flex items-center justify-center bg-black/40"
>
<motion.div
ref={ref}
initial={{ scale: 0.95, opacity: 0 }}
animate={{ scale: 1, opacity: 1 }}
exit={{ scale: 0.95, opacity: 0 }}
transition={{ duration: 0.2, ease: [0.22, 1, 0.36, 1] }}
className="bg-white p-6 rounded"
>
<h2 id="modal-title">Dialog Title</h2>
<button onClick={closeModal}>Close</button>
</motion.div>
</motion.div>
)}
</AnimatePresence>
)
}
export function Example() {
const [open, setOpen] = useState(false)
return (
<>
<button onClick={() => setOpen(true)}>Open</button>
<Modal open={open} closeModal={() => setOpen(false)} />
</>
)
}
SSR-Sicherheit
- Ausgangszustände zwischen Server- und Client-Rendering abgleichen
- Implizite Animationsursprünge vermeiden (
initialimmer explizit setzen) - Motion-Komponenten in Next.js App Router mit
"use client"umschließen
Debugging
Prüfen:
- Falscher Import (Mischen von
motion/reactundframer-motion) - Fehlende
"use client"-Direktive in Next.js App Router - Fehlendes
key-Attribut aufAnimatePresence-Kindern - Hydration-Mismatch (Ausgangszustand unterscheidet sich zwischen SSR und Client)
- Falsche Verwendung der
layout-Prop auf großen Containern, die Reflow-Ruckeln verursacht - Zustandsgesteuerte Animation wird nicht ausgelöst (Abhängigkeitsarrays prüfen)
Qualitätssicherung
- Kein CLS (Cumulative Layout Shift)
- Tastaturbedienung funktioniert
- Fokus in Modalen gefangen
- ARIA-Rollen korrekt (
role="dialog",aria-modal="true") - Reduzierte Bewegung wird respektiert (
useReducedMotion+ CSS-Medienabfrage) - Keine Hydration-Warnungen in Next.js
- Animationen stoppen sauber beim Aushängen (keine Speicherlecks)
AnimatePresence modean allen Einsatzorten explizit gesetzt
Anti-Patterns
- Animieren von Layout-Eigenschaften (
width,height,top,left) - Unendliche Animationen ohne Zweck (immer fragen: Welchen Zustand kommuniziert dies?)
- Übermäßiges Staffeln von Listen (
staggerChildren≤ 0,1s halten; darüber fühlt es sich langsam an) - Ignorieren der Präferenz für reduzierte Bewegung
- Verwenden von
layoutauf großen oder vollständigen Viewport-Containern - Weglassen von
modebeiAnimatePresence(Standardeinstellung"sync"verursacht visuelle Überlappungen) - Verwenden von Bewegung rein zur Dekoration
Philosophie
Bewegung ist Interaktionsdesign.
Abschließende Regel
Wenn Bewegung die UX nicht verbessert → entfernen.
Beispiele
Button-Interaktion
import { motion } from "motion/react"
export function Button() {
return (
<motion.button
whileHover={{ scale: 1.02 }}
whileTap={{ scale: 0.97 }}
transition={{ duration: 0.15, ease: [0.4, 0, 0.2, 1] }}
>
Click me
</motion.button>
)
}
Beispiel für reduzierte Bewegung
import { motion, useReducedMotion } from "motion/react"
export function FadeIn() {
const reduce = useReducedMotion()
return (
<motion.div
initial={{ opacity: 0, y: reduce ? 0 : 24 }}
animate={{ opacity: 1, y: 0 }}
transition={{ duration: reduce ? 0.1 : 0.35, ease: [0.22, 1, 0.36, 1] }}
/>
)
}
Gestaffelte Liste
import { motion } from "motion/react"
const container = {
hidden: {},
visible: {
transition: { staggerChildren: 0.08 } // ≤ 0,1s halten, um Trägheit zu vermeiden
}
}
const item = {
hidden: { opacity: 0, y: 10 },
visible: { opacity: 1, y: 0, transition: { duration: 0.3, ease: [0.22, 1, 0.36, 1] } }
}
export function List() {
return (
<motion.ul variants={container} initial="hidden" animate="visible">
{[1, 2, 3].map(i => (
<motion.li key={i} variants={item}>Item {i}</motion.li>
))}
</motion.ul>
)
}
Modal mit AnimatePresence
import { motion, AnimatePresence } from "motion/react"
export function Modal({ open }: { open: boolean }) {
return (
<AnimatePresence mode="wait">
{open && (
<motion.div
initial={{ opacity: 0, scale: 0.95 }}
animate={{ opacity: 1, scale: 1 }}
exit={{ opacity: 0, scale: 0.95 }}
transition={{ duration: 0.2, ease: [0.22, 1, 0.36, 1] }}
/>
)}
</AnimatePresence>
)
}
Scroll-Parallax
import { useScroll, useTransform, motion } from "motion/react"
export function Parallax() {
const { scrollYProgress } = useScroll()
const y = useTransform(scrollYProgress, [0, 1], [0, -80])
return <motion.div style={{ y }} />
}
Skeleton-Laden
import { motion } from "motion/react"
export function Skeleton() {
return (
<motion.div
className="bg-gray-200 h-6 w-full rounded"
animate={{ opacity: [0.5, 1, 0.5] }}
transition={{
duration: 1.5, // angenehmer Puls – war vorher nicht vorhanden, verursachte schnelles Blitzen
repeat: Infinity,
ease: "easeInOut"
}}
/>
)
}
Geteiltes Layout (Crossfade)
import { motion } from "motion/react"
// layoutId muss pro eingehängter Instanz eindeutig sein.
// Wenn mehrere Instanzen gleichzeitig existieren können, eine eindeutige ID anhängen:
// layoutId={`shared-${item.id}`}
export function Shared() {
return <motion.div layoutId="shared" />
}