---
name: remotion-bits
description: Animation components and utilities for Remotion video projects. Use when building Remotion compositions with text animations, gradient transitions, particle effects, 3D scenes, or staggered motion effects. Provides example bits (complete compositions) and reusable components that can be installed via jsrepo.
---
# Remotion Bits
Animation components and utilities for building Remotion videos. The library's most powerful feature is **Scene3D** - a camera-based 3D presentation system (like impress.js) that enables cinematic multi-section compositions with flying camera moves, step-aware element animations, and Transform3D position management.
**When building any non-trivial composition, prefer Scene3D as your foundation.** It handles camera movement, timing, element positioning, and responsive layout all in one system. Individual components (AnimatedText, Particles, etc.) work best as content placed inside Scene3D steps.
**Prerequisites:** `remotion` >= 4.0, `react` >= 18, `react-dom` >= 18
```bash
# Via npm
npm install remotion-bits
# Via jsrepo (copies source for customization)
npx jsrepo init https://unpkg.com/remotion-bits/registry.json
npx jsrepo add animated-text particle-system scene-3d
```
## Imports
Everything is exported from `remotion-bits`:
```tsx
import {
// 3D Scene System (primary workflow)
Scene3D, Step, Element3D, StepResponsive,
Transform3D, Vector3,
useScene3D, useCamera, useActiveStep,
// Animation Components
AnimatedText, AnimatedCounter, TypeWriter, CodeBlock,
StaggeredMotion, GradientTransition, MatrixRain, ScrollingColumns,
Particles, Spawner, Behavior,
// Core
useViewportRect,
interpolate, Easing,
interpolateColorKeyframes, interpolateGradientKeyframes,
random, resolvePoint, createRect,
} from "remotion-bits";
```
## Core Concepts
### 1. AnimatedValue
Most animation properties accept `AnimatedValue`: a static number OR an array of keyframes interpolated over the animation's duration.
```tsx
opacity: 1 // Static
opacity: [0, 1] // Animate 0→1
opacity: [0, 1, 0.5, 0] // Multi-keyframe: 0→1→0.5→0 evenly spaced
scale: [0.8, 1] // Scale from 80% to 100%
y: [30, 0] // Slide up from 30px offset
```
Keyframes are evenly distributed across the duration. With 4 keyframes over 60 frames: frame 0→20→40→60.
### 2. Responsive Sizing with useViewportRect
**Never hardcode pixel values.** Always use viewport-relative units:
```tsx
const rect = useViewportRect();
// rect.width - composition width (e.g. 1920)
// rect.height - composition height (e.g. 1080)
// rect.vw - 1% of width (19.2)
// rect.vh - 1% of height (10.8)
// rect.vmin - min(vw, vh) - USE THIS for most sizing
// rect.vmax - max(vw, vh)
// rect.cx, cy - center coordinates
const { vmin } = rect;
```
Use `vmin` for font sizes, element dimensions, spacing, and padding. This ensures compositions render identically at 1920×1080, 1080×1920, 3840×2160, etc.
#### Understanding vmin at Common Resolutions
`vmin` = `min(width, height) / 100`. **Always compute what vmin equals in pixels for your composition size before choosing multipliers.**
| Composition Size | Aspect Ratio | vmin (px) | vmin * 8 | vmin * 10 | vmin * 5 |
|------------------|-------------|-----------|----------|-----------|----------|
| 1920×1080 | 16:9 landscape | **10.8** | 86px | 108px | 54px |
| 1080×1920 | 9:16 portrait | **10.8** | 86px | 108px | 54px |
| 1080×1080 | 1:1 square | **10.8** | 86px | 108px | 54px |
| 3840×2160 | 16:9 4K | **21.6** | 173px | 216px | 108px |
| 1280×720 | 16:9 720p | **7.2** | 58px | 72px | 36px |
#### Font Size Reference (at 1920×1080, vmin = 10.8px)
**Use these proven multipliers from production bits. Err on the side of LARGER, not smaller.**
| Role | Multiplier | Pixels at 1080p | Example |
|------|-----------|-----------------|---------|
| Hero / main title | `vmin * 10–15` | 108–162px | Full-screen headline |
| Section heading | `vmin * 6–8` | 65–86px | Scene3D step titles |
| Subheading | `vmin * 4–5` | 43–54px | Card titles, counters |
| Body / card label | `vmin * 2.5–3` | 27–32px | Feature labels, descriptions |
| Code / small text | `vmin * 1.5–2` | 16–22px | Code blocks, captions |
| Fine print | `vmin * 1–1.2` | 11–13px | Code font in dense blocks |
**Common mistake: using `vmin * 3` for headings.** At 1080p that's only 32px - fine for body text but too small for any heading. For prominent headings, start at `vmin * 8` minimum.
#### Aspect Ratio Awareness
The aspect ratio determines which dimension is the "min" for vmin:
- **Landscape (16:9, 1920×1080):** `vmin` is based on height (1080/100 = 10.8). Horizontal space is abundant; vertical space is limited.
- **Portrait (9:16, 1080×1920):** `vmin` is based on width (1080/100 = 10.8). Vertical space is abundant; horizontal space is limited.
- **Square (1:1, 1080×1080):** `vmin = vmax = vh = vw`. All directions equal.
**Layout implications:**
- In landscape, full-width text can be very long - consider `width: vmin * 70` or `maxWidth` constraints
- In portrait, titles may need to wrap - use fewer words or smaller multipliers for width-constrained text
- Use `vmin` for sizes that should scale uniformly regardless of orientation
- Use `vw`/`vh` when sizing should follow a specific axis (e.g., full-width background: `rect.width`)
#### Element Size Reference
| Element | Multiplier | Description |
|---------|-----------|-------------|
| Card width | `vmin * 50–70` | Floating card, info panel |
| Card height | `vmin * 25–40` | Match content needs |
| Card border-radius | `vmin * 1–2` | Subtle rounding |
| Spacing/gap | `vmin * 1–3` | Between elements |
| Padding | `vmin * 2–4` | Inside containers |
| Particle size | `vmin * 1–3` | Individual particle dot |
| Icon size | `vmin * 8–12` | Decorative icons |
### 3. Transition Props Pattern
Components accept a `transition` prop with this shape:
```tsx
transition={{
// Timing
duration: 30, // Duration in frames
delay: 10, // Delay before start
frames: [0, 60], // Or explicit frame range (alternative to duration)
easing: "easeOutCubic", // Easing curve
// Transform (all accept AnimatedValue)
x: [30, 0], // translateX
y: [30, 0], // translateY
z: [0, 100], // translateZ (3D)
scale: [0.8, 1], // uniform scale
scaleX, scaleY, // axis scale
rotate: [0, 360], // 2D rotation (degrees)
rotateX, rotateY, rotateZ, // 3D rotation (degrees)
skew, skewX, skewY, // skew (degrees)
transform: Transform3D[], // 3D transform keyframes (see Transform3D section)
// Visual (all accept AnimatedValue)
opacity: [0, 1],
blur: [10, 0], // Gaussian blur in pixels
borderRadius: [0, 20],
color: ["#ff0000", "#00ff00"], // CSS color interpolation
backgroundColor: ["#000", "#fff"],
}}
```
### 4. Easing Functions
```tsx
type EasingName =
| "linear"
| "easeIn" | "easeOut" | "easeInOut"
| "easeInQuad" | "easeOutQuad" | "easeInOutQuad"
| "easeInCubic" | "easeOutCubic" | "easeInOutCubic"
| "easeInSine" | "easeOutSine" | "easeInOutSine"
| "easeInQuart" | "easeOutQuart" | "easeInOutQuart";
```
Most common: `"easeOutCubic"` for entries, `"easeInOutCubic"` for camera moves.
### 5. Layout & Display Configuration
**CRITICAL: Bits are pre-wrapped with a layout container when displayed in the docs.** The wrapper (`withShowcaseFill`) provides an `AbsoluteFill` with default styling. When building standalone compositions, you must provide this layout yourself.
#### The Layout Wrapper
Bits displayed in docs are automatically wrapped with:
```tsx
```
This means simple bits like `Hello` work because the wrapper centers them and provides background/color.
#### Building Standalone Compositions
When creating compositions for direct use (not displayed through the docs wrapper), you MUST provide your own layout:
```tsx
import { AbsoluteFill } from 'remotion';
export const MyComposition: React.FC = () => {
const rect = useViewportRect();
const { vmin } = rect;
return (
{/* Your content here */}
{/* Steps... */}
);
};
```
#### CSS Variables (Theming)
Bits use CSS variables for consistent theming. These are available when rendering within the docs but **must be defined or replaced with literal values** in standalone projects:
| Variable | Default Value | Usage |
|----------|---------------|-------|
| `--color-primary` | `#ec8b49` | Accent orange |
| `--color-primary-hover` | `#fcc192` | Light orange / text color |
| `--color-background-dark` | `#100f0f` | Dark background |
| `--color-surface-dark` | `#1c1b1a` | Surface/card background |
| `--color-surface-light` | `#343331` | Lighter surface |
| `--color-border-dark` | `#100f0f` | Dark borders |
| `--color-border-light` | `#1c1b1a` | Light borders |
**In standalone projects:** Replace `var(--color-*)` with literal hex values, or define these variables in your HTML/CSS.
#### Common Layout Mistakes
1. **Missing background:** Content renders on transparent/white background. Always set `backgroundColor` on the outermost container.
2. **Missing AbsoluteFill:** Scene3D and full-viewport compositions need `` from remotion as their root.
3. **Using CSS vars without defining them:** `var(--color-primary)` resolves to nothing in a bare Remotion project. Use literal colors.
4. **Hardcoded pixel sizes:** Use `vmin`-based sizing from `useViewportRect()` instead.
5. **Missing font settings:** Set `fontSize`, `fontWeight`, `fontFamily`, and `color` explicitly - there are no inherited defaults in Remotion.
#### Three Layout Patterns
**Simple (centered content, uses wrapper defaults):**
```tsx
// Relies on the outer wrapper for background, centering, font
export const Component = () => (
Hello
);
```
**Self-contained (own background and layout):**
```tsx
export const Component = () => (
{items}
);
```
**Full 3D scene (recommended for complex work):**
```tsx
export const Component = () => {
const rect = useViewportRect();
return (
{/* ... */}
);
};
```
---
## Transform3D (Critical for Complex Scenes)
`Transform3D` represents a 3D transformation (position + rotation + scale) using Three.js internals. It is **immutable by convention** - every method returns a new instance.
```tsx
import { Transform3D, Vector3 } from "remotion-bits";
```
### Creating Transforms
```tsx
const base = Transform3D.identity(); // Origin: position(0,0,0), rotation(0,0,0), scale(1,1,1)
```
### Chaining Transforms
Every method returns a new Transform3D. Chain freely:
```tsx
const cardPosition = base
.translate(vmin * 50, vmin * -20, 0) // Move right and up
.rotateY(-15) // Rotate around Y axis (degrees)
.scaleBy(1.5); // Scale uniformly by 1.5x
```
### Available Methods
```tsx
// Position
transform.translate(x, y, z) // Add to position
transform.translate(vector3) // Add Vector3 to position
// Rotation (angles in DEGREES)
transform.rotateX(degrees) // Rotate around X axis
transform.rotateY(degrees) // Rotate around Y axis
transform.rotateZ(degrees) // Rotate around Z axis
transform.rotateAround(origin, axis, degrees) // Rotate around arbitrary point+axis
// Scale
transform.scaleBy(uniform) // Scale all axes equally
transform.scaleBy(sx, sy, sz) // Scale per-axis
// Composition
transform.multiply(other) // Matrix multiplication
transform.inverse() // Invert transform
transform.lerp(target, alpha) // Linear interpolation (0-1)
transform.clone() // Deep copy
// Randomization (deterministic via seed)
transform.randomTranslate([minX, maxX], [minY, maxY], [minZ, maxZ], seed)
transform.randomRotateX([minDeg, maxDeg], seed)
transform.randomRotateY([minDeg, maxDeg], seed)
transform.randomRotateZ([minDeg, maxDeg], seed)
// Conversion
transform.toProps() // → { x, y, z, rotateX, rotateY, rotateZ, scaleX, scaleY, scaleZ, rotateOrder }
transform.toCSSMatrix3D() // → "matrix3d(...)" CSS string
transform.toMatrix4() // → Three.js Matrix4
```
### Using Transform3D with Step/Element3D
The `.toProps()` method converts a Transform3D to props that Step and Element3D accept:
```tsx
const position = base.translate(vmin * 50, 0, 0).rotateY(-15);
// Spread directly into Step or Element3D
```
This is equivalent to manually specifying `x={...} y={...} z={...} rotateX={...} rotateY={...} rotateZ={...}`.
### Using Transform3D as Keyframes
Pass `Transform3D[]` arrays as the `transform` property for smooth 3D interpolation between positions:
```tsx
const start = base.translate(0, vmin * 20, 0);
const end = base.translate(0, 0, 0);
Animates from start to end
```
Transform keyframes use quaternion slerp for rotation (no gimbal lock) and linear interpolation for position and scale.
### Vector3
Three.js `Vector3` is re-exported for position math:
```tsx
const offset = new Vector3(0, -vmin * 2, 0);
const farOffset = offset.clone().multiplyScalar(4.0); // Scale the offset
const combined = offset.clone().add(new Vector3(vmin * 5, 0, 0));
```
---
## Scene3D System (3D Presentations)
Scene3D creates camera-based 3D presentations (like impress.js). The camera flies between Steps; content is placed in 3D space.
### Architecture
```
Scene3D (perspective, timing)
├── Step (camera target 1) - children visible during this step
├── Step (camera target 2) - children visible during this step
├── ...
├── StepResponsive - element that animates differently per step
├── StepResponsive - another step-aware element
└── (any other children - always rendered)
```
### Scene3D Container
```tsx
{/* Steps and content */}
```
### Steps (Camera Targets)
Steps define where the camera flies to. They execute sequentially. Content inside a Step is visible when that step is active.
```tsx
{/* Content shown during this step */}
...
```
**Step timing model:**
- Steps play sequentially: step1 → transition → step2 → transition → step3
- `stepDuration` (on Scene3D): default duration each step is active
- `duration` (on Step): override for specific step
- `transitionDuration` (on Scene3D): how long the camera takes to move between steps
- Total composition should be ≥ sum of all step durations
### Element3D (3D Positioned Content)
Places content at a specific 3D position, independent of camera:
```tsx
Content positioned in 3D space
```
### StepResponsive (Step-Aware Animations)
The key to complex scenes. Elements define how they should look/position at each step, and animate between states when the camera moves:
```tsx
Title That Follows Camera
```
**StepResponsive key behaviors:**
- Properties **accumulate/inherit**: if step "elements" doesn't set opacity, it keeps the value from the last step that set it
- Arrays flatten to their final value when moving to the next step (no re-animation of past keyframes)
- `transform` accepts `Transform3D[]` arrays - the primary way to position elements in 3D
- `duration: "step"` makes the animation last the entire step duration
- You can map the same props to multiple step IDs to hold position across steps
**Mapping same props to multiple steps** (common pattern):
```tsx
const mapToAllElementSteps = (props) => ({
'elements': props,
'element-particles': props,
'element-text': props,
'element-code': props,
});
Elements
```
---
## Building Complex Scenes (Architecture Guide)
**This is the recommended approach for any non-trivial composition.** Scene3D provides camera management, step-based timing, 3D element positioning, and step-responsive animations - eliminating the need to manually manage `useCurrentFrame()`, ``, or CSS transforms.\n\n### Step 1: Plan the Scene Structure
Decide on the major sections (acts) and what the camera shows in each:
```
intro → elements → element-particles → element-text → ... → transitions → scenes → outro
```
Each section = one Step. Steps execute sequentially.
### Step 2: Pre-compute All Positions
Use `useMemo` to build a position tree. This is THE critical architectural pattern:
```tsx
const positions = useMemo(() => {
const { vmin } = rect;
const base = Transform3D.identity();
// Define base positions for each scene section
const elementsBase = base.translate(0, -vmin * 120, 0).rotateX(15);
const transitionsBase = base.translate(vmin * 200, vmin * 50, 0).rotateY(-15);
const scenesBase = base.translate(-vmin * 120, vmin * 70, 0).rotateY(15);
// Derive sub-positions from bases
const cardW = vmin * 70;
const particlesCard = elementsBase.translate(-cardW, -vmin * 40, 0).rotateY(15);
const textCard = elementsBase.translate(0, -vmin * 50, vmin * 10).rotateX(10);
return {
base,
elements: {
base: elementsBase,
cards: { particles: particlesCard, text: textCard },
},
transitions: { base: transitionsBase },
scenes: { base: scenesBase },
};
}, [rect.width, rect.height]); // Re-compute on resize
```
**Why pre-compute positions?**
- Separation of layout from rendering
- Positions can be derived from each other (hierarchy)
- Easy to adjust entire sections by changing the base
- StepResponsive needs position references, not inline calculations
### Step 3: Define Steps
```tsx
```
### Step 4: Add Step-Responsive Elements
Titles, icons, and persistent elements that move with the camera:
```tsx
```
### GradientTransition
```tsx
```
### MatrixRain
```tsx
```
### ScrollingColumns
```tsx
```
### Particle System
```tsx
{/* Multiple children = random selection per particle */}
```
---
## Procedural Content Generation
For grids, backgrounds, and data-driven visuals, use deterministic `random()`:
```tsx
import { random } from 'remotion-bits';
const items = useMemo(() => {
const palette = ['#fb4934', '#b8bb26', '#fabd2f', '#83a598'];
const result = [];
for (let r = 0; r < 10; r++) {
for (let c = 0; c < 20; c++) {
const seed = `grid-${r}-${c}`;
const colorIndex = Math.floor(random(seed + 'color') * palette.length);
const dist = Math.sqrt(r * r + c * c);
result.push(
);
}
}
return result;
}, [vmin]);
```
`random(seed)` is deterministic - same seed always returns same value. Use unique string seeds per element.
---
## Utility Functions
### interpolate (non-monotonic)
Unlike Remotion's built-in, supports non-monotonic input ranges:
```tsx
import { interpolate, Easing } from "remotion-bits";
// Hold then animate
interpolate(frame, [0, 30, 30, 60], [0, 0, 100, 100]);
// With easing
interpolate(frame, [0, 60], [0, 100], { easing: "easeOutCubic" });
// Clamp extrapolation
interpolate(frame, [0, 60], [0, 100], { extrapolateLeft: 'clamp', extrapolateRight: 'clamp' });
```
### Color Interpolation
```tsx
import { interpolateColorKeyframes } from "remotion-bits";
// Perceptually uniform (Oklch) color transitions
const color = interpolateColorKeyframes(["#ff0000", "#00ff00", "#0000ff"], progress);
```
### Geometry
```tsx
import { resolvePoint, createRect, Rect } from "remotion-bits";
const point = resolvePoint(rect, "center"); // { x: 960, y: 540 }
const point2 = resolvePoint(rect, { x: "50%", y: "25%" }); // { x: 960, y: 270 }
```
---
## Bit Metadata Format
Bits export a `metadata` object and a `Component`:
```tsx
export const metadata = {
name: "MyBit",
description: "Description of the bit.",
tags: ["tag1", "tag2"],
duration: 300, // Total frames
width: 1920,
height: 1080,
registry: {
name: "bit-my-bit",
title: "My Bit",
description: "Registry description.",
type: "bit" as const,
add: "when-needed" as const,
registryDependencies: ["animated-text", "scene-3d", "use-viewport-rect"],
dependencies: [],
files: [{ path: "path/to/MyBit.tsx" }],
},
};
export const Component: React.FC = () => { /* ... */ };
```
---
## Common Patterns
### Floating Card Container
```tsx
const FloatingCard = ({ children }) => (
{children}
);
```
### Scene with Entry Animations per Step
```tsx
{/* Content appears when camera arrives */}
```
### Step-Responsive Title Tracking Camera
```tsx
Section Title
```
### Animated Grid with Wave Timing
```tsx
const dist = Math.sqrt(Math.pow(r - centerRow, 2) + Math.pow(c - centerCol, 2));
const delay = 30 + dist * 2; // Ripple outward from center
```
### Exit Transitions on Steps
```tsx
{/* Content blurs out when camera leaves */}
```
### Element3D with Transform Keyframes
```tsx
slides up into place
```
---
## Reference Documentation
For exhaustive API details:
- [references/components.md](references/components.md) - Complete component props tables
- [references/utilities.md](references/utilities.md) - All utility functions
- [references/patterns.md](references/patterns.md) - More animation recipes and examples