(null)
const [hovered, setHovered] = useState(false)
// Smooth transition to hover state
useFrame(() => {
if (!meshRef.current) return
const targetScale = hovered ? 1.2 : 1
meshRef.current.scale.lerp(
new THREE.Vector3(targetScale, targetScale, targetScale),
0.1 // Smoothing factor
)
})
return (
) => {
e.stopPropagation()
setHovered(true)
}}
onPointerOut={() => setHovered(false)}
>
)
}
```
**Interaction Notes**:
- Use `lerp` for smooth transitions
- `stopPropagation` prevents event bubbling
- Keep hover effects subtle (1.1x-1.2x scale max)
---
## Performance Optimization Checklist
### 1. Conditional Rendering
**Device Detection**:
```tsx
const isMobile = /iPhone|iPad|iPod|Android/i.test(navigator.userAgent)
if (isMobile) {
return // Skip 3D on mobile
}
return
```
### 2. Lazy Loading
**Load 3D only when visible**:
```tsx
import dynamic from 'next/dynamic'
const Scene = dynamic(() => import('@/components/three/Scene'), {
ssr: false, // Disable SSR for Three.js
loading: () => Loading 3D...
})
```
### 3. Frame Budget
**Throttle animations on low FPS**:
```tsx
useFrame((state, delta) => {
// Skip frame if delta > 33ms (below 30fps)
if (delta > 0.033) return
// Your animation code
})
```
### 4. Memory Management
**Dispose geometries and materials**:
```tsx
useEffect(() => {
return () => {
// Cleanup on unmount
if (meshRef.current) {
meshRef.current.geometry.dispose()
meshRef.current.material.dispose()
}
}
}, [])
```
### 5. Level of Detail (LOD)
**Reduce complexity at distance**:
```tsx
import { Lod } from '@react-three/drei'
{/* Close */}
{/* Medium */}
{/* Far */}
```
---
## Responsive Patterns
### Breakpoint-Based 3D
```tsx
'use client'
import { useEffect, useState } from 'react'
export function useResponsive3D() {
const [show3D, setShow3D] = useState(true)
useEffect(() => {
const checkViewport = () => {
const width = window.innerWidth
setShow3D(width >= 768) // Only on tablet+
}
checkViewport()
window.addEventListener('resize', checkViewport)
return () => window.removeEventListener('resize', checkViewport)
}, [])
return show3D
}
// Usage
function MyComponent() {
const show3D = useResponsive3D()
return show3D ? :
}
```
---
## Common UI Patterns
### 1. Glassmorphic 3D Card
**Specs**:
- Transparent material (opacity: 0.2-0.4)
- Subtle reflections (metalness: 0.1-0.3)
- Backface culling disabled (see through)
- Slight blur via post-processing (optional)
### 2. 3D Icon Buttons
**Specs**:
- Small geometry (< 500 triangles)
- On-hover rotation (15-30 degrees max)
- Color transition (0.3s ease)
- No shadows (performance)
### 3. Parallax Background Layers
**Specs**:
- 2-3 layers max
- Depth separation: z = [-10, -5, 0]
- Scroll-based position update (throttled)
- Reduced motion fallback
---
## Accessibility & Fallbacks
### Reduced Motion Support
```tsx
'use client'
import { useReducedMotion } from 'framer-motion'
export function AccessibleScene({ children }) {
const prefersReducedMotion = useReducedMotion()
if (prefersReducedMotion) {
return // Show static version
}
return
}
```
### Progressive Enhancement
```tsx
'use client'
import { Suspense } from 'react'
import { ErrorBoundary } from 'react-error-boundary'
export function Safe3DScene() {
return (
}>
}>
)
}
```
---
## Bundle Size Optimization
### Tree-Shaking Drei Components
**Import only what you need**:
```tsx
// ❌ Bad (imports entire library)
import { Box, Sphere, RoundedBox } from '@react-three/drei'
// ✅ Good (tree-shakeable)
import { Box } from '@react-three/drei/core/Box'
import { Sphere } from '@react-three/drei/core/Sphere'
```
### Code Splitting
```tsx
// Lazy load heavy components
const HeavyScene = lazy(() => import('./HeavyScene'))
// Only load when needed
{showAdvanced && }
```
---
## Next.js Specific Patterns
### App Router (Next.js 13+)
**Client Component Marker**:
```tsx
'use client' // REQUIRED at top of file
import { Canvas } from '@react-three/fiber'
```
**Server Component Integration**:
```tsx
// page.tsx (Server Component)
import dynamic from 'next/dynamic'
const ClientScene = dynamic(() => import('@/components/three/Scene'), {
ssr: false
})
export default function Page() {
return (
Server-rendered content
{/* Client-only 3D */}
)
}
```
---
## Common Pitfalls to Avoid
### ❌ Don't:
- Use 3D for critical UI (buttons, forms, navigation)
- Render complex scenes on every page
- Ignore mobile performance
- Block main thread with heavy calculations
- Use default antialias (too expensive)
### ✅ Do:
- Use 3D for enhancement only
- Lazy load and conditionally render
- Test on low-end devices
- Use Web Workers for heavy math
- Disable antialias, use CSS instead
---
## Example Use Cases
### Use Case 1: Landing Page Hero
- **3D Element**: Floating gradient mesh background
- **Performance**: Low poly (< 1000 triangles), static lighting
- **Fallback**: CSS gradient background
### Use Case 2: Product Card Hover
- **3D Element**: Card lifts with depth shadow
- **Performance**: Single mesh, transform-only animation
- **Fallback**: CSS 3D transform
### Use Case 3: Dashboard Background
- **3D Element**: Animated particles in brand colors
- **Performance**: < 200 particles, no collisions
- **Fallback**: Static background pattern
---
## Advanced Patterns
For more complex scenarios, see:
- **references/3d-ui-patterns.md** - Advanced 3D UI component patterns
- **references/performance-guide.md** - Deep performance optimization techniques
- **references/shader-basics.md** - Custom shader materials for unique effects
---
## Output Format
When providing 3D integration guidance, structure as:
```
## 3D Integration: [Component Name]
### Overview
- Purpose: [What 3D effect achieves]
- Performance Impact: [Low/Medium/High]
- Device Support: [Desktop/Mobile/Both]
### Implementation
1. Dependencies: [npm packages needed]
2. Component Code: [React component]
3. Canvas Setup: [Canvas configuration]
### Optimizations
- [Performance optimization 1]
- [Performance optimization 2]
- [Performance optimization 3]
### Responsive Behavior
- Desktop: [Full 3D experience]
- Tablet: [Simplified version]
- Mobile: [Static fallback or disabled]
### Accessibility
- Reduced motion: [Fallback]
- Keyboard nav: [If applicable]
- Screen readers: [ARIA labels]
```
---
**Remember**: 3D should enhance, not hinder. Performance is non-negotiable. Always provide graceful fallbacks.