Loopwind

Generate images and videos from React + Tailwind CSS templates using the loopwind CLI.

Install

openclaw skills install @tomtev/loopwind

loopwind

A CLI tool for generating images and videos from JSX templates using Tailwind CSS and Satori. Templates live in a .loopwind/ directory alongside your codebase.

Quick Start

Loopwind is a CLI tool for generating images and videos with React and Tailwind CSS. It's designed to be used with AI Agents and Cursor.

Installation

bash

curl -fsSL https://loopwind.dev/install.sh | bash

This installs loopwind to ~/.loopwind/ and adds the loopwind command to your PATH. Requires Node.js 18+.

Initialize in Your Project

Navigate to any project folder and run:

bash

loopwind init

This creates .loopwind/loopwind.json — a configuration file with your project's theme colors.

Install AI Skill

Give your AI agent expertise in loopwind:

bash

npx skills add https://loopwind.dev/skill.md

This installs a skill that teaches Claude Code (or other AI agents) how to create templates, use animation classes, and render images/videos.

Use with Claude Code

With the loopwind skill installed, Claude has deep knowledge of template structure, animation classes, and Tailwind CSS patterns for Satori. Just ask:

text

Create an OG image for my blog post about TypeScript tips

text

Create an animated intro video for my YouTube channel

Claude will create optimized templates and render the final output automatically.

Install a Template

1. Official Templates

bash

loopwind add image-template
loopwind add video-template

Templates are installed to: .loopwind/<template>/

Benefits:

Templates are local to your project
Version controlled with your project
Easy to share within your team

Render a Template

bash

loopwind render template-name '{"title":"Hello World","subtitle":"Built with loopwind"}'

or use a local props file:

bash

loopwind render template-name props.json

Commands

`loopwind add <source>`

Install a template from various sources:

bash

# Official templates
loopwind add image-template
loopwind add video-template

These will be downloaded to .loopwind/<template>/

`loopwind list`

List all installed templates:

bash

loopwind list

`loopwind render <template> <props> [options]`

Render an image or video:

bash

# Image with inline props
loopwind render banner-hero '{"title":"Hello World"}'

# Video with inline props
loopwind render video-intro '{"title":"Welcome"}'

# Using a props file
loopwind render banner-hero props.json

# Custom output
loopwind render banner-hero '{"title":"Hello"}' --out custom-name.png

# Different format
loopwind render banner-hero '{"title":"Hello"}' --format jpeg

Options:

--out, -o - Output filename (default: <template>.<ext> in current directory)
--format - Output format: png, jpeg, svg (images only)
--quality - JPEG quality 1-100 (default: 92)

`loopwind validate <template>`

Validate a template:

bash

loopwind validate banner-hero

Checks:

Template file exists and is valid React
export const meta exists and is valid
Required props are defined
Fonts exist (if specified)

`loopwind init`

Initialize loopwind in a project:

bash

loopwind init

Creates .loopwind/loopwind.json configuration file with your project's design tokens.

Animation Classes (Video Only)

Use Tailwind-style animation classes - no manual calculations needed:

tsx

// Fade in: starts at 0ms, lasts 500ms
<h1 style={tw('enter-fade-in/0/500')}>Hello</h1>

// Loop: ping effect every 500ms
<div style={tw('loop-ping/500')} />

// Combined with easing
<h1 style={tw('ease-out enter-bounce-in-up/0/600')}>Title</h1>

See Animation for the complete reference.

Next Steps

Templates

Templates are React components that define your images and videos. They use Tailwind CSS for styling and export metadata that loopwind uses for rendering.

Installing Templates

Official Templates

bash

loopwind add image-template
loopwind add video-template

Templates are installed to .loopwind/<template-name>/.

Direct URLs

bash

loopwind add https://example.com/templates/my-template.json

Local Filesystem

bash

loopwind add ./my-templates/banner-hero
loopwind add /Users/you/templates/social-card

Image Templates

Basic Structure

tsx

// .loopwind/banner-hero/template.tsx
export const meta = {
  name: "banner-hero",
  type: "image",
  description: "Hero banner with gradient background",
  size: { width: 1600, height: 900 },
  props: { title: "string", subtitle: "string" }
};

export default function BannerHero({ title, subtitle, tw }) {
  return (
    <div style={tw('flex flex-col justify-center items-center w-full h-full bg-gradient-to-br from-purple-600 to-blue-500 p-12')}>
      <h1 style={tw('text-7xl font-bold text-white mb-4')}>
        {title}
      </h1>
      <p style={tw('text-2xl text-white/80')}>
        {subtitle}
      </p>
    </div>
  );
}

Rendering Images

bash

# Render with inline props
loopwind render banner-hero '{"title":"Hello World","subtitle":"Welcome"}'

# Custom output name
loopwind render banner-hero '{"title":"Hello"}' --out custom-name.png

# Different format
loopwind render banner-hero '{"title":"Hello"}' --format jpeg --quality 95

# Use a props file
loopwind render banner-hero props.json

Output Formats

Format	Best For
PNG (default)	Transparency, sharp text, logos
JPEG	Photographs, gradients, smaller files
SVG	Vector graphics, scalable designs

Video Templates

Basic Structure

tsx

// .loopwind/video-intro/template.tsx
export const meta = {
  name: "video-intro",
  type: "video",
  description: "Animated intro with bounce-in title",
  size: { width: 1920, height: 1080 },
  video: { fps: 30, duration: 3 },
  props: { title: "string" }
};

export default function VideoIntro({ tw, title }) {
  return (
    <div style={tw('flex items-center justify-center w-full h-full bg-gradient-to-br from-blue-600 to-purple-700')}>
      <h1 style={tw('text-8xl font-bold text-white ease-out enter-bounce-in-up/0/600')}>
        {title}
      </h1>
    </div>
  );
}

Rendering Videos

bash

# Render with inline props
loopwind render video-intro '{"title":"Welcome!"}' --out intro.mp4

# Faster encoding with FFmpeg
loopwind render video-intro '{"title":"Welcome!"}' --ffmpeg

# Higher quality (lower CRF = better)
loopwind render video-intro '{"title":"Welcome!"}' --crf 18

FPS and Duration

tsx

video: { fps: 30, duration: 3 }  // 90 frames total

FPS	Use Case
24	Cinematic look, smaller files
30	Standard web video
60	Smooth animations

Video-Specific Props

Templates receive these additional props:

frame - Current frame number (0 to totalFrames - 1)
progress - Animation progress from 0 to 1

tsx

export default function MyVideo({ frame, progress }) {
  // frame: 0, 1, 2, ... 89 (for 3s @ 30fps)
  // progress: 0.0 at start, 0.5 at middle, 1.0 at end
}

Encoding Options

Encoder	Command	Use Case
WASM (default)	`loopwind render ...`	CI/CD, no dependencies
FFmpeg	`loopwind render ... --ffmpeg`	Faster, smaller files

Install FFmpeg: brew install ffmpeg (macOS)

Animation Classes

Use Tailwind-style animation classes for videos:

tsx

// Enter animations: enter-{type}/{delay}/{duration}
<h1 style={tw('enter-fade-in/0/500')}>Fade in at start</h1>
<h1 style={tw('enter-bounce-in-up/300/400')}>Bounce in after 300ms</h1>

// Exit animations: exit-{type}/{start}/{duration}
<div style={tw('exit-fade-out/2500/500')}>Fade out at 2.5s</div>

// Loop animations: loop-{type}/{duration}
<div style={tw('loop-float/1000')}>Continuous floating</div>
<div style={tw('loop-spin/1000')}>Spinning</div>

// Easing
<h1 style={tw('ease-out enter-slide-left/0/500')}>Smooth slide</h1>

See the full Animation documentation for all classes.

Common Sizes

Social Media

Twitter/X Card: 1200x675
Facebook/OG: 1200x630
Instagram Post: 1080x1080
LinkedIn Post: 1200x627

Web Graphics

Hero Banner: 1920x1080
Blog Header: 1600x900
Thumbnail: 640x360

Example Templates

Open Graph Image

tsx

export const meta = {
  name: "og-image",
  type: "image",
  size: { width: 1200, height: 630 },
  props: { title: "string", description: "string" }
};

export default function OGImage({ tw, image, title, description }) {
  return (
    <div style={tw('flex w-full h-full bg-white')}>
      <div style={tw('flex-1 flex flex-col justify-between p-12')}>
        <img src={image('logo.svg')} style={tw('h-12 w-auto')} />
        <div>
          <h1 style={tw('text-5xl font-bold text-gray-900 mb-4')}>{title}</h1>
          <p style={tw('text-xl text-gray-600')}>{description}</p>
        </div>
        <p style={tw('text-gray-400')}>yoursite.com</p>
      </div>
    </div>
  );
}

Animated Intro

tsx

export const meta = {
  name: "animated-intro",
  type: "video",
  size: { width: 1920, height: 1080 },
  video: { fps: 60, duration: 3 },
  props: { title: "string", subtitle: "string" }
};

export default function AnimatedIntro({ tw, title, subtitle }) {
  return (
    <div style={tw('flex flex-col items-center justify-center w-full h-full bg-background')}>
      <h1 style={tw('text-8xl font-bold text-foreground ease-out enter-bounce-in-up/0/400')}>
        {title}
      </h1>
      <p style={tw('text-2xl text-muted-foreground mt-4 ease-out enter-fade-in-up/300/400')}>
        {subtitle}
      </p>
    </div>
  );
}

Next Steps

Layouts - Wrap templates with reusable layouts
Embedding Images - Using the image() helper
Animation - Full animation reference
Styling - Tailwind & shadcn/ui integration
Fonts - Custom fonts

Layouts

Layouts let you wrap templates with consistent headers, footers, and styling. A child template specifies a layout in its meta, and the layout receives the child content as a children prop.

Basic Usage

Layout Template

Create a layout template that receives children:

tsx

// .loopwind/base-layout/template.tsx
export const meta = {
  name: 'base-layout',
  type: 'image',
  size: { width: 1200, height: 630 },
  props: {},
};

export default function BaseLayout({ tw, children }) {
  return (
    <div style={tw('flex flex-col w-full h-full bg-background')}>
      {/* Header */}
      <div style={tw('flex items-center px-8 py-4 border-b border-border')}>
        <span style={tw('text-2xl font-bold text-primary')}>loopwind</span>
      </div>

      {/* Content slot */}
      <div style={tw('flex flex-1')}>
        {children}
      </div>

      {/* Footer */}
      <div style={tw('flex items-center justify-between px-8 py-4 border-t border-border')}>
        <span style={tw('text-muted-foreground')}>loopwind.dev</span>
      </div>
    </div>
  );
}

Usage in Templates

Reference the layout using a relative path:

tsx

// .loopwind/blog-post/template.tsx
export const meta = {
  name: 'blog-post',
  type: 'image',
  layout: '../base-layout', // Layout controls size
  props: {
    title: 'string',
    excerpt: 'string',
  },
};

export default function BlogPost({ tw, title, excerpt }) {
  return (
    <div style={tw('flex flex-col justify-center p-12')}>
      <h1 style={tw('text-5xl font-bold text-foreground mb-4 text-balance')}>
        {title}
      </h1>
      <p style={tw('text-xl text-muted-foreground leading-relaxed')}>
        {excerpt}
      </p>
    </div>
  );
}

Render

bash

loopwind render blog-post '{"title":"Hello World","excerpt":"My first post"}'

The output uses the layout's size (1200x630) with the child content inside.

Key Concepts

Size

When using a layout, the layout's size controls the final output dimensions. The child template doesn't need a size property.

Path Resolution

Use relative paths to reference layouts:

tsx

layout: '../base-layout'      // Sibling directory
layout: './shared/layout'     // Subdirectory
layout: '../../layouts/main'  // Parent's sibling

Props Flow

The layout receives:

All standard helpers (tw, image, qr, template, etc.)
children prop containing the rendered child content
Animation context (frame, progress) for video layouts

tsx

export default function Layout({ tw, children, frame, progress }) {
  // tw, image, qr, template, path, textPath all available
  return (
    <div style={tw('flex w-full h-full')}>
      {children}
    </div>
  );
}

Video Layouts

Layouts work with video templates. Both the layout and child can use animations:

tsx

// .loopwind/video-layout/template.tsx
export const meta = {
  name: 'video-layout',
  type: 'video',
  size: { width: 1920, height: 1080 },
  video: { fps: 60, duration: 4 },
  props: {},
};

export default function VideoLayout({ tw, children }) {
  return (
    <div style={tw('flex flex-col w-full h-full bg-background')}>
      {/* Animated header */}
      <div style={tw('flex items-center px-12 py-6 ease-out enter-slide-down/0/500')}>
        <span style={tw('text-3xl font-bold text-primary')}>loopwind</span>
      </div>

      {/* Content */}
      <div style={tw('flex flex-1')}>
        {children}
      </div>

      {/* Animated footer */}
      <div style={tw('flex px-12 py-6 ease-out enter-fade-in/500/400')}>
        <span style={tw('text-muted-foreground')}>loopwind.dev</span>
      </div>
    </div>
  );
}

Example: Consistent OG Images

Create a layout for all your OG images:

tsx

// .loopwind/og-layout/template.tsx
export const meta = {
  name: 'og-layout',
  type: 'image',
  size: { width: 1200, height: 630 },
  props: {},
};

export default function OGLayout({ tw, image, children }) {
  return (
    <div style={tw('flex w-full h-full bg-background')}>
      {/* Content area */}
      <div style={tw('flex flex-col flex-1 p-12')}>
        {/* Logo */}
        <div style={tw('flex items-center gap-3 mb-auto')}>
          <img src={image('logo.svg')} style={tw('h-10 w-auto')} />
          <span style={tw('text-2xl font-bold')}>MyBrand</span>
        </div>

        {/* Slot for page-specific content */}
        <div style={tw('flex flex-1 items-center')}>
          {children}
        </div>

        {/* Domain */}
        <span style={tw('text-muted-foreground mt-auto')}>mybrand.com</span>
      </div>
    </div>
  );
}

Then create page-specific templates:

tsx

// .loopwind/og-blog/template.tsx
export const meta = {
  name: 'og-blog',
  type: 'image',
  layout: '../og-layout',
  props: {
    title: 'string',
    author: 'string',
  },
};

export default function OGBlog({ tw, title, author }) {
  return (
    <div style={tw('flex flex-col')}>
      <span style={tw('text-sm text-muted-foreground uppercase tracking-wider mb-2')}>
        Blog Post
      </span>
      <h1 style={tw('text-4xl font-bold text-foreground mb-4 text-balance')}>
        {title}
      </h1>
      <span style={tw('text-muted-foreground')}>By {author}</span>
    </div>
  );
}

Next Steps

Templates - Template structure and metadata
Animation - Animation classes for video layouts
Helpers - Using image(), qr(), and template()

Embedding Images

Use the image() helper to embed images in your templates. It supports loading from props, template directories, and URLs.

Prop-based Images

Pass the prop name to load an image path from props:

tsx

export const meta = {
  name: "product-card",
  type: "image",
  size: { width: 1200, height: 630 },
  props: {
    title: "string",
    background: "string?"
  }
};

export default function ProductCard({ tw, image, title, background }) {
  // Use fallback if no background prop provided
  const bgSrc = background
    ? image('background')
    : 'https://images.unsplash.com/photo-1557682250-33bd709cbe85?w=1200';

  return (
    <div style={tw('relative w-full h-full')}>
      <img
        src={bgSrc}
        style={tw('absolute inset-0 w-full h-full object-cover')}
      />
      <div style={tw('relative z-10 p-12')}>
        <h1 style={tw('text-6xl font-bold text-white')}>{title}</h1>
      </div>
    </div>
  );
}

The image('background') helper loads from the background prop value (file path or URL).

Direct File Images

Load images directly from your template directory by including the file extension:

tsx

export default function ChangelogItem({ tw, image, text }) {
  return (
    <div style={tw('flex items-center gap-4')}>
      {/* Load check.svg from template directory */}
      <img
        src={image('check.svg')}
        style={tw('w-6 h-6')}
      />
      <span style={tw('text-lg')}>{text}</span>
    </div>
  );
}

You can also use subdirectories:

tsx

<img src={image('assets/icons/star.svg')} />
<img src={image('shared/logo.png')} />

Template directory structure:

text

.loopwind/my-template/
├── template.tsx
├── check.svg           ← image('check.svg')
└── assets/
    └── icons/
        └── star.svg    ← image('assets/icons/star.svg')

URLs

The image() helper also supports loading images from URLs:

json

{
  "background": "https://example.com/image.jpg"
}

Supported Formats

JPEG (.jpg, .jpeg)
PNG (.png)
GIF (.gif)
WebP (.webp)
SVG (.svg)

Image Positioning

Use Tailwind's object-fit utilities:

tsx

export default function ImageGrid({ tw, image, img1, img2, img3 }) {
  return (
    <div style={tw('flex gap-4 w-full h-full p-8 bg-gray-100')}>
      {/* Cover - fills entire area, may crop */}
      <img
        src={image('img1')}
        style={tw('w-full h-full object-cover rounded-lg')}
      />

      {/* Contain - fits within area, may letterbox */}
      <img
        src={image('img2')}
        style={tw('w-full h-full object-contain')}
      />

      {/* Fill - stretches to fill */}
      <img
        src={image('img3')}
        style={tw('w-full h-full object-fill')}
      />
    </div>
  );
}

Troubleshooting

Images Not Loading

Check file paths are relative to the props file:

json

{
  "background": "./images/bg.jpg"
}

Absolute paths won't work.

Optimize Image Sizes

Use appropriately sized images before embedding:

bash

convert large-image.jpg -resize 1600x900 optimized.jpg

Next Steps

Templates - Creating image and video templates
Animation - Animation classes for videos
Styling - Tailwind & shadcn/ui integration

Animation

loopwind provides Tailwind-style animation classes that work with time to create smooth video animations without writing custom code.

Note: Animation classes only work with video templates and GIFs. For static images, animations will have no effect since there's no time context.

Quick Start

tsx

export default function MyVideo({ tw, title, subtitle }) {
  return (
    <div style={tw('flex flex-col items-center justify-center w-full h-full bg-black')}>
      {/* Bounce in from below: starts at 0, lasts 400ms */}
      <h1 style={tw('text-8xl font-bold text-white ease-out enter-bounce-in-up/0/400')}>
        {title}
      </h1>

      {/* Fade in with upward motion: starts at 300ms, lasts 400ms */}
      <p style={tw('text-2xl text-white/80 mt-4 ease-out enter-fade-in-up/300/400')}>
        {subtitle}
      </p>

      {/* Continuous floating animation: repeats every 1s (1000ms) */}
      <div style={tw('mt-8 text-4xl loop-float/1000')}>
        ⬇️
      </div>
    </div>
  );
}

Animation Format

loopwind uses three types of animations with millisecond timing:

Type	Format	Description
Enter	`enter-{type}/{start}/{duration}`	Animations that play when entering
Exit	`exit-{type}/{start}/{duration}`	Animations that play when exiting
Loop	`loop-{type}/{duration}`	Continuous looping animations

All timing values are in milliseconds (1000ms = 1 second).

Utility-Based Animations

In addition to predefined animations, loopwind supports Tailwind utility-based animations that let you animate any transform or opacity property directly:

tsx

// Slide in 20px from the left
<div style={tw('enter-translate-x-5/0/1000')}>Content</div>

// Rotate 90 degrees on entrance
<div style={tw('enter-rotate-90/0/500')}>Spinning</div>

// Fade to 50% opacity in a loop
<div style={tw('loop-opacity-50/1000')}>Pulsing</div>

// Scale down with negative value
<div style={tw('enter--scale-50/0/800')}>Shrinking</div>

Supported Utilities

Utility	Format	Description	Example
translate-x	`enter-translate-x-{value}`	Translate horizontally	`enter-translate-x-5` = 20px `enter-translate-x-full` = 100% `enter-translate-x-[20px]` = 20px
translate-y	`enter-translate-y-{value}`	Translate vertically	`loop-translate-y-10` = 40px `enter-translate-y-1/2` = 50% `enter-translate-y-[5rem]` = 80px
opacity	`enter-opacity-{n}`	Set opacity (0-100)	`enter-opacity-50` = 50%
scale	`enter-scale-{n}`	Scale element (0-200)	`enter-scale-100` = 1.0x
rotate	`enter-rotate-{n}`	Rotate in degrees	`enter-rotate-45` = 45°
skew-x	`enter-skew-x-{n}`	Skew on X axis in degrees	`enter-skew-x-12` = 12°
skew-y	`enter-skew-y-{n}`	Skew on Y axis in degrees	`exit-skew-y-6` = 6°

Translate value formats:

Numeric: 5 = 20px (Tailwind spacing scale: 1 unit = 4px)
Keywords: full = 100%
Fractions: 1/2 = 50%, 1/3 = 33.333%, 2/3 = 66.666%, etc.
Arbitrary values: [20px], [5rem], [10%] (rem converts to px: 1rem = 16px)

All utilities work with:

All prefixes: enter-, exit-, loop-, animate-
Negative values: Prefix with - (e.g., -translate-x-5, -rotate-45)
Timing syntax: Add /start/duration (e.g., enter-translate-x-5/0/800)

Translate Animations

tsx

// Numeric (Tailwind spacing): 20px (5 * 4px)
<div style={tw('enter-translate-x-5/0/500')}>Content</div>

// Keyword: Full width (100%)
<div style={tw('enter-translate-y-full/0/800')}>Dropping full height</div>

// Fraction: Half width (50%)
<div style={tw('enter-translate-x-1/2/0/600')}>Slide in halfway</div>

// Arbitrary values: Exact px or rem
<div style={tw('enter-translate-y-[20px]/0/500')}>Slide 20px</div>
<div style={tw('enter-translate-x-[5rem]/0/800')}>Slide 5rem (80px)</div>

// Loop with fractions
<div style={tw('loop-translate-y-1/4/1000')}>Oscillate 25%</div>

// Negative values
<div style={tw('exit--translate-y-8/2000/500')}>Rising</div>

Opacity Animations

tsx

// Fade to 100% opacity
<div style={tw('enter-opacity-100/0/500')}>Fading In</div>

// Fade to 50% opacity
<div style={tw('enter-opacity-50/0/800')}>Half Opacity</div>

// Pulse between 50% and 100%
<div style={tw('loop-opacity-50/1000')}>Pulsing</div>

// Fade out to 0%
<div style={tw('exit-opacity-0/2500/500')}>Vanishing</div>

Scale Animations

tsx

// Scale from 0 to 100% (1.0x)
<div style={tw('enter-scale-100/0/500')}>Growing</div>

// Scale to 150% (1.5x)
<div style={tw('enter-scale-150/0/800')}>Enlarging</div>

// Pulse scale in a loop
<div style={tw('loop-scale-110/1000')}>Breathing</div>

// Scale down to 50%
<div style={tw('exit-scale-50/2000/500')}>Shrinking</div>

Rotate Animations

tsx

// Rotate 90 degrees
<div style={tw('enter-rotate-90/0/500')}>Quarter Turn</div>

// Rotate 180 degrees
<div style={tw('enter-rotate-180/0/1000')}>Half Turn</div>

// Continuous rotation in loop (360 degrees per cycle)
<div style={tw('loop-rotate-360/2000')}>Spinning</div>

// Rotate backwards with negative value
<div style={tw('enter--rotate-45/0/500')}>Counter Rotation</div>

Skew Animations

tsx

// Skew on X axis
<div style={tw('enter-skew-x-12/0/500')}>Slanted</div>

// Skew on Y axis
<div style={tw('enter-skew-y-6/0/800')}>Tilted</div>

// Oscillating skew in loop
<div style={tw('loop-skew-x-6/1000')}>Wobbling</div>

// Negative skew
<div style={tw('exit--skew-x-12/2000/500')}>Reverse Slant</div>

Combining Utilities

You can combine multiple utility animations on the same element:

tsx

// Translate and rotate together
<div style={tw('enter-translate-y-10/0/500 enter-rotate-45/0/500')}>
  Flying In
</div>

// Fade and scale
<div style={tw('enter-opacity-100/0/800 enter-scale-100/0/800')}>
  Appearing
</div>

// Enter with translate, exit with rotation
<div style={tw('enter-translate-x-5/0/500 exit-rotate-180/2500/500')}>
  Slide and Spin
</div>

Bracket Notation

For more CSS-like syntax, you can use brackets with units:

tsx

// Using bracket notation with seconds
<h1 style={tw('enter-slide-up/[0.6s]/[1.5s]')}>Hello</h1>

// Using bracket notation with milliseconds
<h1 style={tw('enter-fade-in/[300ms]/[800ms]')}>World</h1>

// Mix and match - plain numbers are milliseconds
<h1 style={tw('enter-bounce-in/0/[1.2s]')}>Mixed</h1>

Enter Animations

Format: enter-{type}/{startMs}/{durationMs}

startMs - when the animation begins (milliseconds from start)
durationMs - how long the animation lasts

When values are omitted (enter-fade-in), it uses the full video duration.

Fade Animations

Simple opacity transitions with optional direction.

tsx

// Fade in from 0ms to 500ms
<h1 style={tw('enter-fade-in/0/500')}>Hello</h1>

// Fade in with upward motion
<h1 style={tw('enter-fade-in-up/0/600')}>Hello</h1>

Class	Description
`enter-fade-in/0/500`	Fade in (opacity 0 → 1)
`enter-fade-in-up/0/500`	Fade in + slide up (30px)
`enter-fade-in-down/0/500`	Fade in + slide down (30px)
`enter-fade-in-left/0/500`	Fade in + slide from left (30px)
`enter-fade-in-right/0/500`	Fade in + slide from right (30px)

Slide Animations

Larger movement (100px) with fade.

tsx

// Slide in from left: starts at 0, lasts 500ms
<div style={tw('enter-slide-left/0/500')}>Content</div>

// Slide up from bottom: starts at 200ms, lasts 600ms
<div style={tw('enter-slide-up/200/600')}>Content</div>

Class	Description
`enter-slide-left/0/500`	Slide in from left (100px)
`enter-slide-right/0/500`	Slide in from right (100px)
`enter-slide-up/0/500`	Slide in from bottom (100px)
`enter-slide-down/0/500`	Slide in from top (100px)

Bounce Animations

Playful entrance with overshoot effect.

tsx

// Bounce in with scale overshoot
<h1 style={tw('enter-bounce-in/0/500')}>Bouncy!</h1>

// Bounce in from below
<div style={tw('enter-bounce-in-up/0/600')}>Pop!</div>

Class	Description
`enter-bounce-in/0/500`	Bounce in with scale overshoot
`enter-bounce-in-up/0/500`	Bounce in from below
`enter-bounce-in-down/0/500`	Bounce in from above
`enter-bounce-in-left/0/500`	Bounce in from left
`enter-bounce-in-right/0/500`	Bounce in from right

Scale & Zoom Animations

Size-based transitions.

tsx

// Scale in from 50%
<div style={tw('enter-scale-in/0/500')}>Growing</div>

// Zoom in from 0%
<div style={tw('enter-zoom-in/0/1000')}>Zooming</div>

Class	Description
`enter-scale-in/0/500`	Scale up from 50% to 100%
`enter-zoom-in/0/500`	Zoom in from 0% to 100%

Rotate & Flip Animations

Rotation-based transitions.

tsx

// Rotate in 180 degrees
<div style={tw('enter-rotate-in/0/500')}>Spinning</div>

// 3D flip on X axis
<div style={tw('enter-flip-in-x/0/500')}>Flipping</div>

Class	Description
`enter-rotate-in/0/500`	Rotate in from -180°
`enter-flip-in-x/0/500`	3D flip on horizontal axis
`enter-flip-in-y/0/500`	3D flip on vertical axis

Exit Animations

Format: exit-{type}/{startMs}/{durationMs}

startMs - when the exit animation begins
durationMs - how long the exit animation lasts

Exit animations use the same timing system but animate elements out.

tsx

// Fade out starting at 2500ms, lasting 500ms (ends at 3000ms)
<h1 style={tw('exit-fade-out/2500/500')}>Goodbye</h1>

// Combined enter and exit on same element
<h1 style={tw('enter-fade-in/0/500 exit-fade-out/2500/500')}>
  Hello and Goodbye
</h1>

Class	Description
`exit-fade-out/2500/500`	Fade out (opacity 1 → 0)
`exit-fade-out-up/2500/500`	Fade out + slide up
`exit-fade-out-down/2500/500`	Fade out + slide down
`exit-fade-out-left/2500/500`	Fade out + slide left
`exit-fade-out-right/2500/500`	Fade out + slide right
`exit-slide-up/2500/500`	Slide out upward (100px)
`exit-slide-down/2500/500`	Slide out downward (100px)
`exit-slide-left/2500/500`	Slide out to left (100px)
`exit-slide-right/2500/500`	Slide out to right (100px)
`exit-scale-out/2500/500`	Scale out to 150%
`exit-zoom-out/2500/500`	Zoom out to 200%
`exit-rotate-out/2500/500`	Rotate out to 180°
`exit-bounce-out/2500/500`	Bounce out with scale
`exit-bounce-out-up/2500/500`	Bounce out upward
`exit-bounce-out-down/2500/500`	Bounce out downward
`exit-bounce-out-left/2500/500`	Bounce out to left
`exit-bounce-out-right/2500/500`	Bounce out to right

Loop Animations

Format: loop-{type}/{durationMs}

Loop animations repeat every {durationMs} milliseconds:

/1000 = 1 second loop
/500 = 0.5 second loop
/2000 = 2 second loop

When duration is omitted (loop-bounce), it defaults to 1000ms (1 second).

tsx

// Pulse opacity every 500ms
<div style={tw('loop-fade/500')}>Pulsing</div>

// Bounce every 800ms
<div style={tw('loop-bounce/800')}>Bouncing</div>

// Full rotation every 2000ms
<div style={tw('loop-spin/2000')}>Spinning</div>

Class	Description
`loop-fade/{ms}`	Opacity pulse (0.5 → 1 → 0.5)
`loop-bounce/{ms}`	Bounce up and down
`loop-spin/{ms}`	Full 360° rotation
`loop-ping/{ms}`	Scale up + fade out (radar effect)
`loop-wiggle/{ms}`	Side to side wiggle
`loop-float/{ms}`	Gentle up and down floating
`loop-pulse/{ms}`	Scale pulse (1.0 → 1.05 → 1.0)
`loop-shake/{ms}`	Shake side to side

Easing Functions

Add an easing class before the animation class to control the timing curve.

tsx

// Ease in (accelerate)
<h1 style={tw('ease-in enter-fade-in/0/1000')}>Accelerating</h1>

// Ease out (decelerate) - default
<h1 style={tw('ease-out enter-fade-in/0/1000')}>Decelerating</h1>

// Ease in-out (smooth)
<h1 style={tw('ease-in-out enter-fade-in/0/1000')}>Smooth</h1>

// Strong cubic easing
<h1 style={tw('ease-out-cubic enter-bounce-in/0/500')}>Dramatic</h1>

Class	Description	Best For
`linear`	Constant speed	Mechanical motion
`ease-in`	Slow start, fast end	Exit animations
`ease-out`	Fast start, slow end (default)	Enter animations
`ease-in-out`	Slow start and end	Subtle transitions
`ease-in-cubic`	Strong slow start	Dramatic exits
`ease-out-cubic`	Strong fast start	Impactful entrances
`ease-in-out-cubic`	Strong both ends	Emphasis animations
`ease-in-quart`	Very strong slow start	Powerful exits
`ease-out-quart`	Very strong fast start	Punchy entrances
`ease-in-out-quart`	Very strong both ends	Maximum drama

Per-Animation-Type Easing

You can apply different easing functions to enter, exit, and loop animations on the same element using enter-ease-*, exit-ease-*, and loop-ease-* classes.

tsx

// Different easing for enter and exit
<h1 style={tw('enter-ease-out-cubic enter-fade-in/0/500 exit-ease-in exit-fade-out/2500/500')}>
  Smooth entrance, sharp exit
</h1>

// Loop with linear easing, enter with bounce
<div style={tw('enter-ease-out enter-bounce-in/0/400 loop-ease-linear loop-fade/1000')}>
  Bouncy entrance, linear loop
</div>

// Default easing still works (applies to all animations)
<div style={tw('ease-in-out enter-fade-in/0/500 exit-fade-out/2500/500')}>
  Same easing for both
</div>

// Mix default with specific overrides
<div style={tw('ease-out enter-fade-in/0/500 exit-ease-in-cubic exit-fade-out/2500/500')}>
  Default ease-out for enter, cubic-in for exit
</div>

How it works:

Default easing (ease-*) applies to ALL animations if no specific override is set
Specific easing (enter-ease-*, exit-ease-*, loop-ease-*) overrides the default for that animation type
If both are present, specific easing takes priority for its animation type

Available easing classes:

Default (all animations)	Enter only	Exit only	Loop only
`ease-in`	`enter-ease-in`	`exit-ease-in`	`loop-ease-in`
`ease-out`	`enter-ease-out`	`exit-ease-out`	`loop-ease-out`
`ease-in-out`	`enter-ease-in-out`	`exit-ease-in-out`	`loop-ease-in-out`
`ease-in-cubic`	`enter-ease-in-cubic`	`exit-ease-in-cubic`	`loop-ease-in-cubic`
`ease-out-cubic`	`enter-ease-out-cubic`	`exit-ease-out-cubic`	`loop-ease-out-cubic`
`ease-in-out-cubic`	`enter-ease-in-out-cubic`	`exit-ease-in-out-cubic`	`loop-ease-in-out-cubic`
`ease-in-quart`	`enter-ease-in-quart`	`exit-ease-in-quart`	`loop-ease-in-quart`
`ease-out-quart`	`enter-ease-out-quart`	`exit-ease-out-quart`	`loop-ease-out-quart`
`ease-in-out-quart`	`enter-ease-in-out-quart`	`exit-ease-in-out-quart`	`loop-ease-in-out-quart`
`linear`	`enter-ease-linear`	`exit-ease-linear`	`loop-ease-linear`
`ease-spring`	`enter-ease-spring`	`exit-ease-spring`	`loop-ease-spring`

Spring Easing

Spring easing creates natural, physics-based bouncy animations. Use the built-in ease-spring easing or create custom springs with configurable parameters.

tsx

// Default spring easing
<h1 style={tw('ease-spring enter-bounce-in/0/500')}>Bouncy spring!</h1>

// Per-animation-type spring
<div style={tw('enter-ease-spring enter-fade-in/0/500 exit-ease-out exit-fade-out/2500/500')}>
  Spring entrance, smooth exit
</div>

// Custom spring with parameters: ease-spring/mass/stiffness/damping
<h1 style={tw('ease-spring/1/100/10 enter-scale-in/0/800')}>
  Custom spring (mass=1, stiffness=100, damping=10)
</h1>

// More bouncy spring (lower damping)
<div style={tw('ease-spring/1/170/8 enter-bounce-in-up/0/600')}>
  Extra bouncy!
</div>

// Stiffer spring (higher stiffness, faster)
<div style={tw('ease-spring/1/200/12 enter-fade-in-up/0/400')}>
  Snappy spring
</div>

// Per-animation-type custom springs
<div style={tw('enter-ease-spring/1/150/10 enter-fade-in/0/500 exit-ease-spring/1/100/15 exit-fade-out/2500/500')}>
  Different springs for enter and exit
</div>

Spring parameters:

Parameter	Description	Effect when increased	Default
mass	Mass of the spring	Slower, more inertia	1
stiffness	Spring stiffness	Faster, snappier	100
damping	Damping coefficient	Less bounce, smoother	10

Common spring presets:

tsx

// Gentle bounce (default)
ease-spring/1/100/10

// Extra bouncy
ease-spring/1/170/8

// Snappy (no bounce)
ease-spring/1/200/15

// Slow and bouncy
ease-spring/2/100/8

// Fast and tight
ease-spring/0.5/300/20

How spring works:

Default ease-spring - Uses a pre-calculated spring curve optimized for most use cases
Custom ease-spring/mass/stiffness/damping - Generates a physics-based spring curve using the damped harmonic oscillator formula
The spring automatically calculates its ideal duration to reach the final state
Works with all animation types: ease-spring, enter-ease-spring, exit-ease-spring, loop-ease-spring

Combining Enter and Exit

You can use both enter and exit animations on the same element:

tsx

export default function EnterExit({ tw, title }) {
  return (
    <div style={tw('flex items-center justify-center w-full h-full bg-black')}>
      {/* Fade in during first 500ms, fade out during last 500ms (assuming 3s video) */}
      <h1 style={tw('text-8xl font-bold text-white enter-fade-in/0/500 exit-fade-out/2500/500')}>
        {title}
      </h1>
    </div>
  );
}

The opacities from multiple animations are multiplied together, so you get smooth transitions that combine properly.

Staggered Animations

Create sequenced animations by offsetting start times:

tsx

export default function StaggeredList({ tw, items }) {
  return (
    <div style={tw('flex flex-col gap-4')}>
      {/* First item: starts at 0ms, lasts 300ms */}
      <div style={tw('ease-out enter-fade-in-left/0/300')}>
        {items[0]}
      </div>

      {/* Second item: starts at 100ms, lasts 300ms */}
      <div style={tw('ease-out enter-fade-in-left/100/300')}>
        {items[1]}
      </div>

      {/* Third item: starts at 200ms, lasts 300ms */}
      <div style={tw('ease-out enter-fade-in-left/200/300')}>
        {items[2]}
      </div>
    </div>
  );
}

Dynamic Staggering

For dynamic lists, calculate the timing programmatically:

tsx

export default function DynamicStagger({ tw, items }) {
  return (
    <div style={tw('flex flex-col gap-4')}>
      {items.map((item, i) => {
        const start = i * 100;      // Each item starts 100ms later
        const duration = 300;       // Each animation lasts 300ms

        return (
          <div
            key={i}
            style={tw(`ease-out enter-fade-in-up/${start}/${duration}`)}
          >
            {item}
          </div>
        );
      })}
    </div>
  );
}

Common Patterns

Intro Sequence

tsx

export default function IntroVideo({ tw, title, subtitle, logo }) {
  return (
    <div style={tw('flex flex-col items-center justify-center w-full h-full bg-gradient-to-br from-blue-600 to-purple-700')}>
      {/* Logo appears first */}
      <img
        src={logo}
        style={tw('h-20 mb-8 ease-out enter-scale-in/0/300')}
      />

      {/* Title bounces in */}
      <h1 style={tw('text-7xl font-bold text-white ease-out enter-bounce-in-up/200/500')}>
        {title}
      </h1>

      {/* Subtitle fades in last */}
      <p style={tw('text-2xl text-white/80 mt-4 ease-out enter-fade-in-up/400/700')}>
        {subtitle}
      </p>
    </div>
  );
}

Text Reveal

tsx

export default function TextReveal({ tw, words }) {
  return (
    <div style={tw('flex flex-wrap gap-2 justify-center')}>
      {words.split(' ').map((word, i) => (
        <span
          key={i}
          style={tw(`text-4xl font-bold ease-out enter-fade-in-up/${i * 100}/200`)}
        >
          {word}
        </span>
      ))}
    </div>
  );
}

Looping Background Element

tsx

export default function AnimatedBackground({ tw, children }) {
  return (
    <div style={tw('relative w-full h-full')}>
      {/* Floating background circles */}
      <div style={tw('absolute top-10 left-10 w-20 h-20 rounded-full bg-white/10 loop-float/2000')} />
      <div style={tw('absolute bottom-20 right-20 w-32 h-32 rounded-full bg-white/10 loop-fade/1500')} />

      {/* Main content */}
      <div style={tw('relative z-10')}>
        {children}
      </div>
    </div>
  );
}

Full Enter/Exit Animation

tsx

export default function FullAnimation({ tw, title }) {
  return (
    <div style={tw('flex items-center justify-center w-full h-full bg-black')}>
      {/* Enter: starts at 0, lasts 400ms. Exit: starts at 2600ms, lasts 400ms */}
      <h1 style={tw('text-8xl font-bold text-white ease-out enter-bounce-in-up/0/400 exit-fade-out-up/2600/400')}>
        {title}
      </h1>
    </div>
  );
}

Programmatic Animations

For complete control beyond animation classes, use progress and frame directly.

Available Props

Prop	Type	Description
`progress`	`number`	0 to 1 through the video (0% to 100%)
`frame`	`number`	Current frame number (0, 1, 2, ... totalFrames-1)

These are only available in video templates. Use them when animation classes aren't flexible enough.

Using `frame`

tsx

export default function FrameAnimation({ tw, frame, title }) {
  // Color cycling using frame number
  const hue = (frame * 5) % 360; // Cycle through colors

  // Pulsing based on frame
  const fps = 30;
  const pulse = Math.sin(frame / fps * Math.PI * 2) * 0.2 + 0.8; // 0.6 to 1.0

  return (
    <div style={tw('flex items-center justify-center w-full h-full bg-black')}>
      <h1 style={{
        ...tw('text-8xl font-bold'),
        color: `hsl(${hue}, 70%, 60%)`,
        transform: `scale(${pulse})`
      }}>
        {title}
      </h1>
    </div>
  );
}

Using `progress`

tsx

export default function ProgressAnimation({ tw, progress, title }) {
  // Custom fade based on progress
  const opacity = progress < 0.3 ? progress / 0.3 : 1;

  // Custom scale based on progress
  const scale = 0.8 + progress * 0.2; // 0.8 to 1.0

  return (
    <div style={tw('flex items-center justify-center w-full h-full bg-gray-900')}>
      <h1 style={{
        ...tw('text-8xl font-bold text-white'),
        opacity,
        transform: `scale(${scale})`
      }}>
        {title}
      </h1>
    </div>
  );
}

Custom Easing

tsx

export default function CustomEasing({ tw, progress, title }) {
  // Smoothstep easing
  const eased = progress * progress * (3 - 2 * progress);

  // Elastic easing
  const elastic = Math.pow(2, -10 * progress) * Math.sin((progress - 0.075) * (2 * Math.PI) / 0.3) + 1;

  return (
    <div style={tw('flex items-center justify-center w-full h-full')}>
      <h1 style={{
        ...tw('text-8xl font-bold'),
        opacity: eased,
        transform: `translateY(${(1 - elastic) * 100}px)`
      }}>
        {title}
      </h1>
    </div>
  );
}

When to Use Programmatic Animations

Use progress/frame instead of animation classes when you need:

Custom easing functions (elastic, bounce with specific curves beyond built-in ease-spring)
Color cycling or gradients based on time
Mathematical animations (sine waves, spirals, etc.)
Complex multi-property animations that need precise coordination
Conditional logic based on specific frame numbers

For everything else, prefer animation classes - they're simpler and more maintainable.

Animating Along Paths

Animate elements along SVG paths with proper rotation using built-in path helpers:

tsx

export default function PathFollowing({ tw, progress, path }) {
  // Follow a quadratic Bezier curve - one line!
  const rocket = path.followQuadratic(
    { x: 200, y: 400 },   // Start point
    { x: 960, y: 150 },   // Control point
    { x: 1720, y: 400 },  // End point
    progress
  );

  return (
    <div style={{ display: 'flex', ...tw('relative w-full h-full bg-gray-900') }}>
      {/* Draw the path (optional) */}
      <svg width="1920" height="1080" style={{ position: 'absolute' }}>
        <path
          d="M 200 400 Q 960 150 1720 400"
          stroke="rgba(255,255,255,0.2)"
          strokeWidth={2}
          fill="none"
        />
      </svg>

      {/* Element following the path */}
      <div
        style={{
          position: "absolute",
          left: rocket.x,
          top: rocket.y,
          transform: `translate(-50%, -50%) rotate(${rocket.angle}deg)`,
          fontSize: '48px'
        }}
      >
        🚀
      </div>
    </div>
  );
}

Text Path Animations

Combine textPath helpers with animation classes to create animated text along curves:

Rotating text around a circle:

tsx

export default function RotatingCircleText({ tw, textPath, progress }) {
  return (
    <div style={tw('relative w-full h-full bg-black')}>
      {/* Text rotates around circle using progress */}
      {textPath.onCircle(
        "SPINNING TEXT • AROUND • ",
        960,      // center x
        540,      // center y
        400,      // radius
        progress, // rotation offset (0-1 animates full rotation)
        {
          fontSize: "3xl",
          fontWeight: "bold",
          color: "yellow-300"
        }
      )}
    </div>
  );
}

Animated text reveal along a path:

tsx

export default function PathTextReveal({ tw, textPath, progress }) {
  // Create custom path follower that animates position
  const pathFollower = (t) => {
    // Only show characters up to current progress
    const visibleProgress = progress * 1.5; // Extend range for smooth reveal
    const opacity = t < visibleProgress ? 1 : 0;

    // Follow quadratic curve
    const pos = {
      x: (1 - t) * (1 - t) * 200 + 2 * (1 - t) * t * 960 + t * t * 1720,
      y: (1 - t) * (1 - t) * 400 + 2 * (1 - t) * t * 150 + t * t * 400,
      angle: 0
    };

    return { ...pos, opacity };
  };

  return (
    <div style={tw('relative w-full h-full bg-gray-900')}>
      {textPath.onPath(
        "REVEALING TEXT",
        pathFollower,
        {
          fontSize: "4xl",
          fontWeight: "bold",
          color: "blue-300"
        }
      ).map((char, i) => (
        <div key={i} style={{ ...char.props.style, opacity: char.props.style.opacity || 1 }}>
          {char}
        </div>
      ))}
    </div>
  );
}

Staggered character entrance:

tsx

export default function StaggeredCircleText({ tw, textPath }) {
  const text = "HELLO WORLD";

  return (
    <div style={tw('relative w-full h-full bg-slate-900')}>
      {textPath.onCircle(
        text,
        960, 540, 400, 0,
        { fontSize: "4xl", fontWeight: "bold", color: "white" }
      ).map((char, i) => {
        // Stagger fade-in: each character starts 50ms later
        const staggerDelay = i * 50;
        return (
          <div
            key={i}
            style={{
              ...char.props.style,
              ...tw(`enter-fade-in/${staggerDelay}/300 enter-scale-100/${staggerDelay}/300`)
            }}
          >
            {char.props.children}
          </div>
        );
      })}
    </div>
  );
}

Text with bounce entrance along arc:

tsx

export default function BouncyArcText({ tw, textPath }) {
  return (
    <div style={tw('relative w-full h-full bg-gradient-to-br from-purple-600 to-blue-500')}>
      {/* Draw the arc path */}
      <svg width="1920" height="1080" style={{ position: 'absolute' }}>
        <path
          d="M 300 900 A 600 600 0 0 1 1620 900"
          stroke="rgba(255,255,255,0.2)"
          strokeWidth={2}
          fill="none"
          strokeDasharray="5 5"
        />
      </svg>

      {/* Text follows arc with staggered bounce */}
      {textPath.onArc(
        "BOUNCING ON ARC",
        960,  // cx
        300,  // cy
        600,  // radius
        180,  // start angle
        360,  // end angle
        { fontSize: "3xl", fontWeight: "bold", color: "white" }
      ).map((char, i) => (
        <div
          key={i}
          style={{
            ...char.props.style,
            ...tw(`ease-out enter-bounce-in-up/${i * 80}/500`)
          }}
        >
          {char.props.children}
        </div>
      ))}
    </div>
  );
}

Loop animation with text on curve:

tsx

export default function LoopingCurveText({ tw, textPath, frame }) {
  // Calculate wave effect using frame
  const waveOffset = Math.sin(frame / 30 * Math.PI * 2) * 0.1;

  return (
    <div style={tw('relative w-full h-full bg-black')}>
      {textPath.onQuadratic(
        "WAVY TEXT",
        { x: 200, y: 400 },
        { x: 960, y: 150 },
        { x: 1720, y: 400 },
        { fontSize: "4xl", fontWeight: "bold", color: "pink-300" }
      ).map((char, i) => (
        <div
          key={i}
          style={{
            ...char.props.style,
            transform: `${char.props.style.transform} translateY(${Math.sin((i + frame) / 5) * 10}px)`
          }}
        >
          {char.props.children}
        </div>
      ))}
    </div>
  );
}

Tips for animating text paths:

Use progress for smooth rotation on circles and arcs
Map over returned characters to apply individual animations
Combine with animation classes like enter-fade-in, enter-bounce-in, etc.
Stagger character animations by calculating delays: i * delayMs
Use frame for continuous effects like waves or pulsing
Preserve the original transform when adding animations: transform: '${char.props.style.transform} ...'

Common path types:

Quadratic Bezier (Q command):

tsx

// Position: (1-t)²·P0 + 2(1-t)t·P1 + t²·P2
function pointOnQuadraticBezier(p0, p1, p2, t) {
  const x = (1 - t) * (1 - t) * p0.x + 2 * (1 - t) * t * p1.x + t * t * p2.x;
  const y = (1 - t) * (1 - t) * p0.y + 2 * (1 - t) * t * p1.y + t * t * p2.y;
  return { x, y };
}

// Tangent angle
function angleOnQuadraticBezier(p0, p1, p2, t) {
  const dx = 2 * (1 - t) * (p1.x - p0.x) + 2 * t * (p2.x - p1.x);
  const dy = 2 * (1 - t) * (p1.y - p0.y) + 2 * t * (p2.y - p1.y);
  return Math.atan2(dy, dx) * (180 / Math.PI);
}

Cubic Bezier (C command):

tsx

// Position: (1-t)³·P0 + 3(1-t)²t·P1 + 3(1-t)t²·P2 + t³·P3
function pointOnCubicBezier(p0, p1, p2, p3, t) {
  const mt = 1 - t;
  const mt2 = mt * mt;
  const mt3 = mt2 * mt;
  const t2 = t * t;
  const t3 = t2 * t;
  const x = mt3 * p0.x + 3 * mt2 * t * p1.x + 3 * mt * t2 * p2.x + t3 * p3.x;
  const y = mt3 * p0.y + 3 * mt2 * t * p1.y + 3 * mt * t2 * p2.y + t3 * p3.y;
  return { x, y };
}

// Tangent angle
function angleOnCubicBezier(p0, p1, p2, p3, t) {
  const mt = 1 - t;
  const mt2 = mt * mt;
  const t2 = t * t;
  const dx = -3 * mt2 * p0.x + 3 * mt2 * p1.x - 6 * mt * t * p1.x - 3 * t2 * p2.x + 6 * mt * t * p2.x + 3 * t2 * p3.x;
  const dy = -3 * mt2 * p0.y + 3 * mt2 * p1.y - 6 * mt * t * p1.y - 3 * t2 * p2.y + 6 * mt * t * p2.y + 3 * t2 * p3.y;
  return Math.atan2(dy, dx) * (180 / Math.PI);
}

Circle:

tsx

function pointOnCircle(cx, cy, radius, angleRadians) {
  return {
    x: cx + radius * Math.cos(angleRadians),
    y: cy + radius * Math.sin(angleRadians)
  };
}

// Usage
const angleRadians = progress * Math.PI * 2;
const pos = pointOnCircle(300, 300, 100, angleRadians);
const tangentAngle = (angleRadians * 180 / Math.PI) + 90; // Tangent is perpendicular

Tips:

Use progress (0-1) for smooth animation
The translate(-50%, -50%) centers the element on the path
Combine rotation with the translate: translate(-50%, -50%) rotate(${angle}deg)
For text following a path, you can animate individual characters at different progress values

SVG Stroke Animations

Animate SVG path strokes with the stroke-dash classes, perfect for drawing or erasing line art, icons, and illustrations.

How It Works

SVG stroke animations use strokeDasharray and strokeDashoffset CSS properties to create drawing effects:

Enter animations - Draw the stroke from start to finish
Exit animations - Erase the stroke from finish to start
Loop animations - Continuously draw and erase

Format

All stroke-dash animations require the path length in brackets:

tsx

enter-stroke-dash-[length]/start/duration
exit-stroke-dash-[length]/start/duration
loop-stroke-dash-[length]/duration

Basic Examples

tsx

export default function SVGAnimation({ tw }) {
  return (
    <svg width="400" height="200" viewBox="0 0 400 200">
      {/* Draw a curve over 1 second */}
      <path
        d="M10 150 Q 95 10 180 150"
        stroke="black"
        strokeWidth={4}
        fill="none"
        style={tw('enter-stroke-dash-[300]/0/1000')}
      />
    </svg>
  );
}

Enter Animations (Drawing)

Draw strokes from 0% to 100%:

tsx

// Draw a 300px path over 1 second
<path style={tw('enter-stroke-dash-[300]/0/1000')} />

// Draw with spring easing
<path style={tw('ease-spring enter-stroke-dash-[500]/0/1500')} />

// Stagger multiple paths
<path style={tw('enter-stroke-dash-[200]/0/600')} />
<path style={tw('enter-stroke-dash-[200]/200/600')} />
<path style={tw('enter-stroke-dash-[200]/400/600')} />

Exit Animations (Erasing)

Erase strokes from 100% to 0%:

tsx

// Erase starting at 2000ms, lasting 500ms
<path style={tw('exit-stroke-dash-[300]/2000/500')} />

// Draw then erase the same path
<path style={tw('enter-stroke-dash-[400]/0/800 exit-stroke-dash-[400]/2200/800')} />

Loop Animations

Continuously draw and erase:

tsx

// Loop every 2 seconds (draws in first half, erases in second half)
<path style={tw('loop-stroke-dash-[300]/2000')} />

// Faster loop
<path style={tw('loop-stroke-dash-[200]/1000')} />

Getting Path Length

To find the path length for your SVG:

tsx

// In browser console or component:
const path = document.querySelector('path');
const length = path.getTotalLength();
console.log(length); // e.g., 347.89

Then use that value:

tsx

<path style={tw('enter-stroke-dash-[347.89]/0/1000')} />

Complete Example

tsx

export default function DrawingEffect({ tw }) {
  return (
    <div style={tw('flex items-center justify-center w-full h-full bg-gray-900')}>
      <svg width="600" height="400" viewBox="0 0 600 400">
        {/* Checkmark icon drawn in sequence */}
        <path
          d="M100 200 L 200 300 L 400 100"
          stroke="#10b981"
          strokeWidth={8}
          fill="none"
          strokeLinecap="round"
          strokeLinejoin="round"
          style={tw('ease-out enter-stroke-dash-[600]/0/1200')}
        />

        {/* Circle drawn after checkmark */}
        <circle
          cx="250"
          cy="200"
          r="150"
          stroke="#10b981"
          strokeWidth={6}
          fill="none"
          style={tw('ease-out enter-stroke-dash-[942]/1000/1000')}
        />
      </svg>
    </div>
  );
}

Combining with Other Animations

Stroke animations work alongside other animation classes:

tsx

// Fade in while drawing
<path style={tw('enter-stroke-dash-[300]/0/1000 enter-fade-in/0/1000')} />

// Draw with pulsing color
<svg>
  <path
    stroke="url(#gradient)"
    style={tw('enter-stroke-dash-[500]/0/1500')}
  />
  <defs>
    <linearGradient id="gradient">
      <stop offset="0%" stopColor="#8b5cf6" />
      <stop offset="100%" stopColor="#ec4899" />
    </linearGradient>
  </defs>
</svg>

Animated Dashed Strokes (Marching Ants)

For marching ants or animated dashed patterns, use frame or progress directly instead of animation classes:

tsx

export default function MarchingAnts({ tw, frame }) {
  // Calculate animated offset (loops every 30 frames)
  const dashOffset = -(frame % 30) * 2;

  return (
    <div style={tw('flex items-center justify-center w-full h-full bg-gray-900')}>
      <svg width="600" height="400" viewBox="0 0 600 400">
        {/* Marching ants border */}
        <rect
          x="50"
          y="50"
          width="500"
          height="300"
          fill="none"
          stroke="#3b82f6"
          strokeWidth={3}
          strokeDasharray="10 5"
          strokeDashoffset={dashOffset}
        />

        {/* Animated circle with different speed */}
        <circle
          cx="300"
          cy="200"
          r="80"
          fill="none"
          stroke="#10b981"
          strokeWidth={4}
          strokeDasharray="15 8"
          strokeDashoffset={dashOffset * 1.5}
        />
      </svg>
    </div>
  );
}

Tips:

strokeDasharray="10 5" - 10px dash, 5px gap
strokeDashoffset={dashOffset} - animates the pattern position
Negative offset moves forward, positive moves backward
Different speeds: multiply by different values (e.g., dashOffset * 2)

This technique is different from stroke-dash classes:

stroke-dash classes - Draw/erase the stroke (reveal animation)
Marching ants - Move a dashed pattern along the stroke

Performance Tips

Use Tailwind classes when possible - they're optimized for the renderer
Avoid too many nested animations - each adds computation per frame
Use loop animations sparingly - they're computed every frame
Prefer opacity and transform - they're the most performant properties

Next Steps

Templates - Creating image and video templates
Helpers - QR codes, images, and more

Template Helpers

Additional helpers for creating powerful, composable templates.

Overview

Beyond the basics, loopwind provides:

template() - Compose templates together
qr() - Generate QR codes on the fly
config - Access user configuration

For image embedding, see the Images page.

Template Composition

Compose multiple templates together to create complex designs.

Usage

tsx

export default function CompositeCard({ tw, template, title, author, avatar }) {
  return (
    <div style={tw('w-full h-full bg-gradient-to-br from-purple-600 to-blue-500 p-12')}>
      <div style={tw('bg-white rounded-2xl p-8 shadow-xl')}>
        <h1 style={tw('text-4xl font-bold text-gray-900 mb-6')}>{title}</h1>
        
        {/* Embed another template */}
        <div style={tw('mb-6')}>
          {template('user-badge', {
            name: author,
            avatar: avatar
          })}
        </div>
        
        <p style={tw('text-gray-600')}>Published by {author}</p>
      </div>
    </div>
  );
}

How it works:

template(name, props) renders another installed template
The embedded template is rendered at its specified size
You can embed multiple templates in one design
Templates can be nested (template within a template)

Use Cases

1. Reusable components:

tsx

// Create a logo template once, use it everywhere
<div>{template('company-logo', { variant: 'dark' })}</div>

2. Complex layouts:

tsx

// Combine multiple templates into one design
<div style={tw('grid grid-cols-2 gap-4')}>
  {template('product-card', { product: product1 })}
  {template('product-card', { product: product2 })}
</div>

3. Dynamic content:

tsx

// Render templates based on data
{users.map(user => 
  template('user-avatar', { name: user.name, image: user.avatar })
)}

Best Practices

Keep templates focused - Each template should do one thing well
Pass minimal props - Only pass what the embedded template needs
Document dependencies - Note which templates are required in your README
Avoid deep nesting - Too many nested templates can be hard to debug

QR Codes

Generate QR codes dynamically in your templates.

Usage

tsx

export default function QRCard({ tw, qr, title, url }) {
  return (
    <div style={tw('flex flex-col items-center justify-center w-full h-full bg-white p-10')}>
      <h1 style={tw('text-4xl font-bold text-black mb-8')}>{title}</h1>
      
      {/* Generate QR code for the URL */}
      <img src={qr(url)} style={tw('w-64 h-64')} />
      
      <p style={tw('text-gray-600 mt-4')}>{url}</p>
    </div>
  );
}

Props format:

json

{
  "title": "Scan Me",
  "url": "https://example.com"
}

QR Options

You can customize QR code appearance:

tsx

// Basic QR code
<img src={qr('https://example.com')} />

// With error correction level
<img src={qr('https://example.com', { errorCorrectionLevel: 'H' })} />

// With custom size
<img src={qr('https://example.com', { width: 512 })} />

Error correction levels:

L - Low (~7% correction)
M - Medium (~15% correction) - default
Q - Quartile (~25% correction)
H - High (~30% correction)

User Configuration

Access user settings from .loopwind/loopwind.json using the config prop:

tsx

export default function BrandedTemplate({ tw, config, title }) {
  // Access custom colors from loopwind.json
  const primaryColor = config?.colors?.brand || '#6366f1';
  
  return (
    <div style={tw('w-full h-full p-12')}>
      <h1 style={{ 
        ...tw('text-6xl font-bold'),
        color: primaryColor 
      }}>
        {title}
      </h1>
    </div>
  );
}

User's .loopwind/loopwind.json:

json

{
  "colors": {
    "brand": "#ff6b6b"
  },
  "fonts": {
    "sans": ["Inter", "system-ui", "sans-serif"]
  }
}

This allows templates to adapt to user preferences and brand guidelines.

Text on Path

Render text along curves, circles, and custom paths with automatic character positioning and rotation.

Usage

tsx

export default function CircleText({ tw, textPath, message }) {
  return (
    <div style={tw('relative w-full h-full bg-slate-900')}>
      {textPath.onCircle(
        message,
        960,  // center x
        540,  // center y
        400,  // radius
        0,    // rotation offset (0-1)
        {
          fontSize: "4xl",
          fontWeight: "bold",
          color: "white",
          letterSpacing: 0.05
        }
      )}
    </div>
  );
}

Available Functions

All textPath functions return an array of positioned character elements:

textPath.onCircle(text, cx, cy, radius, offset, options?)

tsx

// Text around a circle
textPath.onCircle("HELLO WORLD", 960, 540, 400, 0, {
  fontSize: "4xl",
  color: "white"
})

textPath.onPath(text, pathFollower, options?)

tsx

// Text along any custom path
textPath.onPath("CUSTOM PATH", (t) => ({
  x: 100 + t * 800,
  y: 200 + Math.sin(t * Math.PI) * 100,
  angle: Math.cos(t * Math.PI) * 20
}), {
  fontSize: "2xl",
  fontWeight: "semibold"
})

textPath.onQuadratic(text, p0, p1, p2, options?)

tsx

// Text along a quadratic Bezier curve
textPath.onQuadratic(
  "CURVED TEXT",
  { x: 200, y: 400 },   // start
  { x: 960, y: 100 },   // control point
  { x: 1720, y: 400 },  // end
  { fontSize: "3xl", color: "blue-300" }
)

textPath.onCubic(text, p0, p1, p2, p3, options?)

tsx

// Text along a cubic Bezier curve
textPath.onCubic(
  "S-CURVE",
  { x: 200, y: 600 },   // start
  { x: 600, y: 400 },   // control 1
  { x: 1320, y: 800 },  // control 2
  { x: 1720, y: 600 },  // end
  { fontSize: "3xl", color: "purple-300" }
)

textPath.onArc(text, cx, cy, radius, startAngle, endAngle, options?)

tsx

// Text along a circular arc
textPath.onArc(
  "ARC TEXT",
  960,   // center x
  540,   // center y
  400,   // radius
  0,     // start angle (degrees)
  180,   // end angle (degrees)
  { fontSize: "2xl", color: "pink-300" }
)

Options

All textPath functions accept an optional options object:

typescript

{
  fontSize?: string;      // Tailwind size: "xl", "2xl", "4xl", etc.
  fontWeight?: string;    // Tailwind weight: "bold", "semibold", etc.
  color?: string;         // Tailwind color: "white", "blue-500", etc.
  letterSpacing?: number; // Space between characters (0-1, default: 0)
  style?: any;           // Additional inline styles
}

Examples

Animated rotating text:

tsx

export default function RotatingText({ tw, textPath, progress }) {
  return (
    <div style={tw('relative w-full h-full bg-black')}>
      {textPath.onCircle(
        "SPINNING • TEXT • ",
        960, 540, 400,
        progress,  // Rotate based on video progress
        { fontSize: "3xl", color: "yellow-300" }
      )}
    </div>
  );
}

Multiple text paths:

tsx

export default function MultiPath({ tw, textPath }) {
  return (
    <div style={tw('relative w-full h-full bg-gradient-to-br from-slate-900 to-slate-700')}>
      {/* Text on outer circle */}
      {textPath.onCircle(
        "OUTER RING",
        960, 540, 500, 0,
        { fontSize: "5xl", fontWeight: "bold", color: "white" }
      )}

      {/* Text on inner circle */}
      {textPath.onCircle(
        "inner ring",
        960, 540, 300, 0.5,  // offset by 50% for rotation
        { fontSize: "2xl", color: "white/60" }
      )}
    </div>
  );
}

Text following a drawn path:

tsx

export default function PathText({ tw, textPath }) {
  return (
    <div style={tw('relative w-full h-full bg-gray-900')}>
      {/* Draw the path */}
      <svg width="1920" height="1080" style={{ position: 'absolute' }}>
        <path
          d="M 200 400 Q 960 150 1720 400"
          stroke="rgba(255,255,255,0.2)"
          strokeWidth={2}
          fill="none"
        />
      </svg>

      {/* Text following the path */}
      {textPath.onQuadratic(
        "FOLLOWING THE CURVE",
        { x: 200, y: 400 },
        { x: 960, y: 150 },
        { x: 1720, y: 400 },
        { fontSize: "3xl", fontWeight: "bold", color: "blue-300" }
      )}
    </div>
  );
}

For animated text paths, see Text Path Animations.

Reserved Prop Names

The following prop names are reserved and cannot be used in your template's meta.props:

tw, qr, image, template - Core helpers
path, textPath - Path and text helpers
config, frame, progress - System props

Why? These names are used for loopwind's built-in helpers. Using them as prop names would cause conflicts.

Example:

tsx

// ❌ BAD - 'image' is reserved
export const meta = {
  props: {
    title: "string",
    image: "string"  // Error!
  }
};

// ✅ GOOD - Use descriptive alternatives
export const meta = {
  props: {
    title: "string",
    imageUrl: "string",    // or imageSrc, photoUrl, etc.
    logoUrl: "string"
  }
};

If you try to use a reserved name, you'll get a helpful error:

text

Template uses reserved prop names: image

Try renaming: "image" → "imageUrl" or "imageSrc"

Reserved names: tw, qr, image, template, path, textPath, config, frame, progress

All Props Reference

Every template receives these props:

tsx

export default function MyTemplate({
  // Core helpers (RESERVED - cannot be used as prop names)
  tw,        // Tailwind class converter
  qr,        // QR code generator (this page)
  template,  // Template composer (this page)
  config,    // User config from loopwind.json (this page)
  textPath,  // Text on path helpers (this page)

  // Media helpers (RESERVED)
  image,     // Image embedder → see /images
  path,      // Path following → see /animation

  // Video-specific (RESERVED - only in video templates)
  frame,     // Current frame number → see /templates
  progress,  // Animation progress 0-1 → see /templates

  // Your custom props (use any names EXCEPT the reserved ones above)
  ...props   // Any props from your meta.props
}) {
  // Your template code
}

Next Steps

Styling Templates

Style your templates with Tailwind utility classes and shadcn/ui's beautiful design system.

Quick Start

tsx

export default function MyTemplate({ title, tw }) {
  return (
    <div style={tw('flex items-center justify-center w-full h-full bg-gradient-to-br from-blue-600 to-purple-700')}>
      <h1 style={tw('text-7xl font-bold text-white')}>
        {title}
      </h1>
    </div>
  );
}

The `tw()` Function

Every template receives a tw() function that converts Tailwind classes to inline styles compatible with Satori:

tsx

// Tailwind classes
tw('flex items-center justify-center p-8 bg-blue-500')

// Converts to inline styles:
{
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'center',
  padding: '2rem',
  backgroundColor: '#3b82f6'
}

Basic Usage

tsx

export default function Banner({ title, subtitle, tw }) {
  return (
    <div style={tw('w-full h-full p-12 bg-gray-50')}>
      <h1 style={tw('text-6xl font-bold text-gray-900 mb-4')}>
        {title}
      </h1>
      <p style={tw('text-2xl text-gray-600')}>
        {subtitle}
      </p>
    </div>
  );
}

Combining with Custom Styles

Mix Tailwind classes with custom styles using the spread operator:

tsx

export default function CustomGradient({ title, tw }) {
  return (
    <div
      style={{
        ...tw('flex flex-col items-center justify-center w-full h-full p-20'),
        background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
      }}
    >
      <h1 style={tw('text-8xl font-bold text-white')}>{title}</h1>
    </div>
  );
}

shadcn/ui Design System

loopwind uses shadcn/ui's design system by default, providing semantic color tokens for beautiful, consistent designs.

Default Color Palette

All templates automatically have access to these semantic colors defined in .loopwind/loopwind.json:

typescript

colors: {
  // Primary colors
  primary: '#18181b',           // Main brand color
  'primary-foreground': '#fafafa',

  // Secondary colors
  secondary: '#f4f4f5',         // Subtle accents
  'secondary-foreground': '#18181b',

  // Background
  background: '#ffffff',        // Page background
  foreground: '#09090b',        // Main text color

  // Muted
  muted: '#f4f4f5',            // Subtle backgrounds
  'muted-foreground': '#71717a', // Muted text

  // Accent
  accent: '#f4f4f5',           // Highlight color
  'accent-foreground': '#18181b',

  // Destructive
  destructive: '#ef4444',       // Error/danger states
  'destructive-foreground': '#fafafa',

  // UI Elements
  border: '#e4e4e7',           // Border color
  input: '#e4e4e7',            // Input borders
  ring: '#18181b',             // Focus rings
  card: '#ffffff',             // Card background
  'card-foreground': '#09090b',
}

Using Semantic Colors

tsx

export default function SemanticCard({ title, description, price, tw }) {
  return (
    <div style={tw('bg-card border border-border rounded-lg p-6')}>
      <h2 style={tw('text-card-foreground text-2xl font-bold mb-2')}>
        {title}
      </h2>
      <p style={tw('text-muted-foreground mb-4')}>
        {description}
      </p>
      <div style={tw('text-primary text-3xl font-bold')}>
        ${price}
      </div>
    </div>
  );
}

Opacity Modifiers

Use Tailwind's slash syntax for opacity with any color:

tsx

export default function OpacityExample({ tw }) {
  return (
    <div style={tw('bg-primary/50')}>          {/* 50% opacity */}
      <p style={tw('text-muted-foreground/75')}> {/* 75% opacity */}
        Subtle text
      </p>
      <div style={tw('border border-border/30')}> {/* 30% opacity */}
        Faint border
      </div>
    </div>
  );
}

Supported syntax:

bg-{color}/{opacity} - Background with opacity
text-{color}/{opacity} - Text with opacity
border-{color}/{opacity} - Border with opacity

Text Hierarchy

tsx

// Primary text
tw('text-foreground')

// Secondary/muted text
tw('text-muted-foreground')

// Accent/brand text
tw('text-primary')

// Destructive/error text
tw('text-destructive')

Backgrounds

tsx

// Page background
tw('bg-background')

// Card/elevated surfaces
tw('bg-card')

// Subtle backgrounds
tw('bg-muted')

// Accent backgrounds
tw('bg-accent')

Supported Tailwind Classes

Layout

Display: flex, inline-flex, block, inline-block, hidden
Flex Direction: flex-row, flex-col, flex-row-reverse, flex-col-reverse
Justify: justify-start, justify-end, justify-center, justify-between, justify-around
Align: items-start, items-end, items-center, items-baseline, items-stretch

Spacing

Padding: p-{n}, px-{n}, py-{n}, pt-{n}, pb-{n}, pl-{n}, pr-{n}
Margin: m-{n}, mx-{n}, my-{n}, mt-{n}, mb-{n}, ml-{n}, mr-{n}
Gap: gap-{n}, gap-x-{n}, gap-y-{n}
Sizes: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24, 32, 40, 48, 56, 64

Examples:

tsx

tw('p-4')      // padding: 1rem
tw('px-8')     // paddingLeft: 2rem, paddingRight: 2rem
tw('m-6')      // margin: 1.5rem
tw('gap-4')    // gap: 1rem

Sizing

Width: w-{n}, w-full, w-screen, w-1/2, w-1/3, w-2/3
Height: h-{n}, h-full, h-screen

Examples:

tsx

tw('w-full')   // width: 100%
tw('h-64')     // height: 16rem
tw('w-1/2')    // width: 50%

Typography

Font Size: text-xs, text-sm, text-base, text-lg, text-xl, text-2xl, text-3xl, text-4xl, text-5xl, text-6xl, text-7xl, text-8xl, text-9xl
Font Weight: font-thin, font-light, font-normal, font-medium, font-semibold, font-bold, font-extrabold, font-black
Text Align: text-left, text-center, text-right
Line Height: leading-none, leading-tight, leading-normal, leading-relaxed, leading-loose

Colors

All standard Tailwind colors plus shadcn semantic colors:

Standard colors:

text-{color}-{shade}, bg-{color}-{shade}, border-{color}-{shade}
Colors: red, blue, green, yellow, purple, pink, gray, indigo, teal, orange
Shades: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900

shadcn semantic colors:

text-foreground, text-primary, text-muted-foreground, text-destructive
bg-background, bg-card, bg-muted, bg-accent, bg-primary
border-border, border-input

tsx

tw('text-blue-500')        // Standard Tailwind color
tw('bg-purple-600')        // Standard Tailwind color
tw('text-primary')         // shadcn semantic color
tw('bg-card')              // shadcn semantic color

Position & Layout

Position: relative, absolute, fixed, sticky
Inset: inset-0, top-0, bottom-0, left-0, right-0
Z-Index: z-0, z-10, z-20, z-30, z-40, z-50

Borders

Border Width: border, border-{n}, border-t, border-b, border-l, border-r
Border Radius: rounded, rounded-sm, rounded-md, rounded-lg, rounded-xl, rounded-2xl, rounded-3xl, rounded-full
Border Color: border-{color}-{shade}, border-border, border-input

Effects

Shadow: shadow-sm, shadow, shadow-md, shadow-lg, shadow-xl, shadow-2xl
Opacity: opacity-0, opacity-25, opacity-50, opacity-75, opacity-100

Filters

Blur: blur-none, blur-sm, blur, blur-md, blur-lg, blur-xl
Brightness: brightness-0, brightness-50, brightness-100, brightness-150, brightness-200
Contrast: contrast-0, contrast-50, contrast-100, contrast-150, contrast-200

Gradients

Linear Gradients

tsx

// Gradient direction
tw('bg-gradient-to-r')      // left to right
tw('bg-gradient-to-br')     // top-left to bottom-right
tw('bg-gradient-to-t')      // bottom to top

// Gradient colors
tw('from-blue-500')         // Start color
tw('via-purple-500')        // Middle color
tw('to-pink-500')           // End color

// Complete gradient
tw('bg-gradient-to-r from-blue-500 via-purple-500 to-pink-500')

Gradient Examples

tsx

export default function GradientCard({ title, tw }) {
  return (
    <div style={tw('w-full h-full bg-gradient-to-br from-cyan-500 to-blue-600 p-12')}>
      <h1 style={tw('text-white text-6xl font-bold')}>
        {title}
      </h1>
    </div>
  );
}

Custom Theme Colors

You can override the default shadcn colors or add your own custom colors in .loopwind/loopwind.json:

json

{
  "theme": {
    "colors": {
      "primary": "#3b82f6",
      "primary-foreground": "#ffffff",
      "accent": "#10b981",
      "brand": "#ff6b6b"
    }
  }
}

Then use these custom colors in your templates:

tsx

tw('text-brand')    // Uses your custom brand color
tw('bg-primary')    // Uses your custom primary color
tw('bg-accent')     // Uses your custom accent color

Auto-Detection from tailwind.config.js

loopwind automatically detects and loads your project's Tailwind configuration:

text

your-project/
├── tailwind.config.js  ← Automatically detected
└── .loopwind/
    ├── loopwind.json
    └── templates/

This includes:

Custom colors
Custom spacing values
Custom fonts
Theme extensions
Custom utilities

Complete Example

tsx

export default function ModernCard({ 
  tw, 
  image,
  title, 
  description, 
  category,
  author,
  avatar 
}) {
  return (
    <div style={tw('w-full h-full bg-card')}>
      {/* Hero image */}
      <div style={tw('relative h-2/3')}>
        <img 
          src={image(hero)} 
          style={tw('w-full h-full object-cover')}
        />
        {/* Category badge */}
        <div style={tw('absolute top-4 left-4 bg-primary/90 backdrop-blur px-4 py-2 rounded-full')}>
          <span style={tw('text-sm font-semibold text-primary-foreground')}>
            {category}
          </span>
        </div>
      </div>
      
      {/* Content */}
      <div style={tw('h-1/3 p-8 flex flex-col justify-between')}>
        <div>
          <h2 style={tw('text-3xl font-bold text-foreground mb-2')}>
            {title}
          </h2>
          <p style={tw('text-muted-foreground line-clamp-2')}>
            {description}
          </p>
        </div>
        
        {/* Author */}
        <div style={tw('flex items-center gap-3')}>
          <img 
            src={image(avatar)} 
            style={tw('w-10 h-10 rounded-full border-2 border-border')}
          />
          <span style={tw('text-sm text-muted-foreground')}>
            {author}
          </span>
        </div>
      </div>
    </div>
  );
}

Why This Approach?

Semantic naming: text-primary instead of text-blue-600
Consistency: All templates use the same design language
Flexibility: Easy to customize entire theme
Accessibility: Pre-tested color contrasts
Modern: Same system as shadcn/ui components
Familiar: Standard Tailwind syntax

Next Steps

Font Handling in loopwind

The recommended way to use fonts is through loopwind.json - configure fonts once, use everywhere.

Using Fonts from loopwind.json (Recommended)

Configure fonts in your .loopwind/loopwind.json and use Tailwind classes in templates.

Simple Setup

Define font families in .loopwind/loopwind.json without loading custom fonts (uses system fonts):

json

{
  "fonts": {
    "sans": ["Inter", "system-ui", "-apple-system", "sans-serif"],
    "serif": ["Georgia", "serif"],
    "mono": ["Courier New", "monospace"]
  }
}

Template usage:

tsx

export default function({ title, tw }) {
  return (
    <div style={tw('w-full h-full')}>
      {/* Uses fonts.sans from loopwind.json */}
      <h1 style={tw('font-sans text-6xl font-bold')}>
        {title}
      </h1>

      {/* Uses fonts.mono from loopwind.json */}
      <code style={tw('font-mono text-sm')}>
        {code}
      </code>
    </div>
  );
}

Result: Uses system fonts, falls back to Inter for rendering.

Complete Setup (With Font Files)

Load custom font files for brand-specific typography in .loopwind/loopwind.json:

json

{
  "fonts": {
    "sans": {
      "family": ["Inter", "system-ui", "sans-serif"],
      "files": [
        { "path": "./fonts/Inter-Regular.woff", "weight": 400 },
        { "path": "./fonts/Inter-Bold.woff", "weight": 700 }
      ]
    },
    "mono": {
      "family": ["JetBrains Mono", "monospace"],
      "files": [
        { "path": "./fonts/JetBrainsMono-Regular.woff", "weight": 400 }
      ]
    }
  }
}

Project structure:

text

your-project/
├── .loopwind/
│   ├── loopwind.json
│   └── templates/
└── fonts/
    ├── Inter-Regular.woff
    ├── Inter-Bold.woff
    └── JetBrainsMono-Regular.woff

Template usage (same as before):

tsx

<h1 style={tw('font-sans font-bold')}>
  {/* Uses Inter Bold from loopwind.json */}
  {title}
</h1>

Available classes:

font-sans - Uses fonts.sans from loopwind.json
font-serif - Uses fonts.serif from loopwind.json
font-mono - Uses fonts.mono from loopwind.json

Supported formats:

✅ WOFF (.woff) - Recommended for best compatibility
✅ TTF (.ttf) - Also supported
✅ OTF (.otf) - Also supported
❌ WOFF2 (.woff2) - Not supported by renderer

Font Loading Priority

loopwind loads fonts in this order:

loopwind.json fonts (if configured with files)
Bundled Inter fonts (included with CLI)

This ensures fonts work out of the box with no configuration.

Default Fonts

If no fonts are configured, loopwind uses Inter (Regular 400, Bold 700) which is bundled with the CLI. This means fonts work offline with no configuration required.

Best Practices

✅ Use loopwind.json for project-wide fonts - Configure once, use everywhere
✅ Use font classes - tw('font-sans') instead of fontFamily: 'Inter'
✅ Include fallbacks - Always add system fonts: ["Inter", "system-ui", "sans-serif"]
✅ Match names - First font in family array is used as the loaded font name
✅ Relative paths - Font paths are relative to loopwind.json location

Examples

Minimal Setup (System Fonts)

json

{
  "fonts": {
    "sans": ["Inter", "-apple-system", "sans-serif"]
  }
}

Uses system Inter if available, falls back to Noto Sans for rendering.

Brand Fonts Setup

json

{
  "fonts": {
    "sans": {
      "family": ["Montserrat", "sans-serif"],
      "files": [
        { "path": "./fonts/Montserrat-Regular.woff", "weight": 400 },
        { "path": "./fonts/Montserrat-Bold.woff", "weight": 700 }
      ]
    }
  }
}

Loads and uses Montserrat for all templates.

Multi-Font Setup

json

{
  "fonts": {
    "sans": {
      "family": ["Inter", "sans-serif"],
      "files": [
        { "path": "./fonts/Inter-Regular.woff", "weight": 400 },
        { "path": "./fonts/Inter-Bold.woff", "weight": 700 }
      ]
    },
    "serif": {
      "family": ["Playfair Display", "serif"],
      "files": [
        { "path": "./fonts/Playfair-Regular.woff", "weight": 400 }
      ]
    },
    "mono": {
      "family": ["Fira Code", "monospace"],
      "files": [
        { "path": "./fonts/FiraCode-Regular.woff", "weight": 400 }
      ]
    }
  }
}

Loads different fonts for each style class.

External Font URLs

Load fonts directly from CDNs without downloading files:

json

{
  "fonts": {
    "sans": {
      "family": ["Inter", "sans-serif"],
      "files": [
        {
          "path": "https://unpkg.com/@fontsource/inter@5.0.18/files/inter-latin-400-normal.woff",
          "weight": 400
        },
        {
          "path": "https://unpkg.com/@fontsource/inter@5.0.18/files/inter-latin-700-normal.woff",
          "weight": 700
        }
      ]
    }
  }
}

You can also mix local and external fonts:

json

{
  "fonts": {
    "sans": {
      "family": ["Inter", "sans-serif"],
      "files": [
        { "path": "./fonts/Inter-Regular.woff", "weight": 400 },
        {
          "path": "https://unpkg.com/@fontsource/inter@5.0.18/files/inter-latin-700-normal.woff",
          "weight": 700
        }
      ]
    }
  }
}

Note: Use WOFF format (.woff) for best compatibility. WOFF2 is not supported by the underlying renderer.

Performance

✅ Font caching - Fonts load once and are cached for all renders
✅ Video optimization - 90-frame video loads fonts once, not 90 times
✅ No CDN delays - Local fonts load instantly

Next Steps

loopwind.json

Configure colors and fonts for all your templates in .loopwind/loopwind.json.

File Location

text

your-project/
├── .loopwind/
│   ├── loopwind.json     ← Configuration file
│   └── templates/

Minimal Example

json

{
  "theme": {
    "colors": {
      "primary": "#3b82f6",
      "background": "#ffffff"
    }
  }
}

Theme Colors

Default shadcn/ui Palette

json

{
  "theme": {
    "colors": {
      "primary": "#18181b",
      "primary-foreground": "#fafafa",
      
      "secondary": "#f4f4f5",
      "secondary-foreground": "#18181b",
      
      "background": "#ffffff",
      "foreground": "#09090b",
      
      "muted": "#f4f4f5",
      "muted-foreground": "#71717a",
      
      "accent": "#f4f4f5",
      "accent-foreground": "#18181b",
      
      "destructive": "#ef4444",
      "destructive-foreground": "#fafafa",
      
      "border": "#e4e4e7",
      "input": "#e4e4e7",
      "ring": "#18181b",
      
      "card": "#ffffff",
      "card-foreground": "#09090b"
    }
  }
}

Custom Colors

json

{
  "theme": {
    "colors": {
      "primary": "#3b82f6",
      "brand": "#ff6b6b",
      "success": "#22c55e",
      "warning": "#f59e0b"
    }
  }
}

Use in templates:

tsx

tw('text-brand')      // #ff6b6b
tw('bg-success')      // #22c55e
tw('border-warning')  // #f59e0b

Fonts

Simple (System Fonts)

json

{
  "fonts": {
    "sans": ["Inter", "system-ui", "sans-serif"],
    "serif": ["Georgia", "serif"],
    "mono": ["Courier New", "monospace"]
  }
}

With Font Files

json

{
  "fonts": {
    "sans": {
      "family": ["Inter", "system-ui", "sans-serif"],
      "files": [
        { "path": "./fonts/Inter-Regular.woff", "weight": 400 },
        { "path": "./fonts/Inter-Bold.woff", "weight": 700 }
      ]
    }
  }
}

Paths are relative to loopwind.json.

Supported formats:

✅ WOFF (.woff)
✅ TTF (.ttf)
✅ OTF (.otf)
❌ WOFF2 (.woff2)

External URLs

json

{
  "fonts": {
    "sans": {
      "family": ["Inter", "sans-serif"],
      "files": [
        {
          "path": "https://unpkg.com/@fontsource/inter@5.0.18/files/inter-latin-400-normal.woff",
          "weight": 400
        }
      ]
    }
  }
}

Complete Example

json

{
  "theme": {
    "colors": {
      "primary": "#6366f1",
      "primary-foreground": "#ffffff",
      "background": "#ffffff",
      "foreground": "#0f172a",
      "muted": "#f1f5f9",
      "muted-foreground": "#64748b",
      "border": "#e2e8f0",
      "card": "#ffffff",
      "brand": "#8b5cf6"
    }
  },
  "fonts": {
    "sans": {
      "family": ["Inter", "sans-serif"],
      "files": [
        { "path": "./fonts/Inter-Regular.woff", "weight": 400 },
        { "path": "./fonts/Inter-Bold.woff", "weight": 700 }
      ]
    },
    "serif": {
      "family": ["Playfair Display", "serif"],
      "files": [
        { "path": "./fonts/Playfair-Regular.woff", "weight": 400 }
      ]
    }
  }
}

Schema

typescript

{
  "theme"?: {
    "colors"?: {
      [name: string]: string;  // Hex color
    }
  },
  "fonts"?: {
    [class: string]: string[] | {
      family: string[];
      files: Array<{
        path: string;    // Local or URL
        weight: number;  // 100-900
      }>;
    }
  }
}

Auto-Detection

If no loopwind.json exists, loopwind auto-detects tailwind.config.js:

text

your-project/
├── tailwind.config.js  ← Auto-detected
└── .loopwind/
    └── templates/

Priority:

.loopwind/loopwind.json
tailwind.config.js
Built-in defaults

Next Steps

Styling - Use colors in templates
Fonts - Font configuration details
Getting Started - Setup guide