Documentation

Visual animation authoring for React applications. Create animations visually in dev mode, export to CSS, and ship with zero runtime overhead.

Overview

Flomo provides a visual editor overlay for authoring UI animations during development. Animations are saved to CSS files in your project and compiled into production builds automatically.

Core Principle: Only CSS animations ship to production - no runtime library overhead.

Key Benefits

🔘Zero Runtime Cost - Animations compile to pure CSS, no JavaScript in production
🔘Visual Editor - Point-and-click interface for creating animations
🔘AI-Powered - Generate animations with natural language prompts
🔘Framework Agnostic - Works with Next.js and vanilla React
🔘SSR Safe - Compatible with server-side rendering
🔘TypeScript First - Full type definitions included

Framework Compatibility

Flomo works with React 18+ and supports both modern and traditional setups. Choose the setup guide that matches your project.

Framework	Setup
Next.js 13+ (App Router)	Recommended - run `npx flomodev init` for automatic setup
React (Create React App, Vite, etc.)	Manual - follow the Vanilla React setup below

Installation

Flomo is published to npm and works with all major package managers:

# npm
npm install flomodev

# pnpm
pnpm add flomodev

# yarn
yarn add flomodev

# bun
bun add flomodev

Requirements

🔘React 18.0.0 or higher
🔘React DOM 18.0.0 or higher

Quick Start

Next.js Setup

1. Initialize Flomo (Recommended)

npx flomodev init

This command creates app/styles/flomo-animations.css, the API route for saving animations, and adds the CSS import to your layout.

2. Add FlomoProvider to your layout

app/layout.tsx

import { FlomoProvider } from 'flomodev'
import 'flomodev/dist/index.css'
import './styles/flomo-animations.css'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <FlomoProvider>
          {children}
        </FlomoProvider>
      </body>
    </html>
  )
}

3. Start development

npm run dev

The Flomo overlay appears at the bottom of your page in development mode.

Vanilla React Setup

1. Add FlomoProvider to your app

src/App.tsx

import { FlomoProvider } from 'flomodev'
import 'flomodev/dist/index.css'

function App() {
  return (
    <FlomoProvider devMode={process.env.NODE_ENV === 'development'}>
      {/* Your app content */}
    </FlomoProvider>
  )
}

2. Export animations manually

When you click "Save" in the overlay, animations are stored in localStorage. You can copy the generated CSS from the overlay or access via localStorage.getItem('flomo-animations').

Visual Animation Editor

🔘Point-and-click selection - Click any element to animate it
🔘Live preview - See animations in real-time as you adjust
🔘Instant feedback - Changes apply immediately

AI-Powered Generation

🔘Natural language prompts - Describe what you want: 'fade in from left' or 'bounce on scroll'
🔘Smart detection - AI analyzes your element's role and layout
🔘Stagger support - Animate children, words, or individual letters
🔘Instant generation - Get animations in seconds, not hours

Animation Controls

🔘Duration - 0-5000ms
🔘Delay - 0-5000ms
🔘Easing - 15+ easing functions
🔘Transform - Translate, scale, rotate
🔘Opacity - Fade in/out
🔘Stagger - Sequential animations for groups

Manual Animation Mode

1. Enable Select Mode

Click "Select" in the bottom bar, then click any element on the page.

2. Configure Animation

Choose trigger: onMount, onInView, or onHover. Select animation effect (fade, slide, scale, etc.). Adjust duration, delay, and easing. Set from/to states for transforms.

3. Preview and Apply

Click "Preview" to test the animation, then click "Apply" to save.

4. Export

Click "Save" to persist animations to CSS file.

AI-Powered Generation

Let AI create animations for you. Just describe what you want and watch it come to life.

1. Select Elements (Optional)

Click elements you want to animate, or leave empty and AI will choose smart defaults.

2. Open AI Generation

Click the "Generate with AI" button in the Flomo panel.

3. Describe Your Animation

Type what you want: 'fade in from left with stagger', 'bounce on scroll', etc. Leave blank for automatic suggestions.

4. Review & Apply

Preview the generated animations, then click 'Apply' to add them to your page.

Prompt Ideas

📝 Try these prompts:
   • "fade in from bottom"
   • "slide in from left with stagger"
   • "scale up on hover"
   • "word by word reveal"
   • "bounce in from top"
   • "letter by letter animation"
   • "rotate and fade"
   • "bounce on scroll"

CLI Commands

All commands should be run from your project root:

# Initialize Flomo in your project (Next.js)
npx flomodev init

# Show the dev overlay
npx flomodev show

# Hide the dev overlay
npx flomodev hide

# Clear all animations (CSS and localStorage)
npx flomodev clearall

# Show help
npx flomodev help

Command	Description
`init`	Creates CSS file, API route, and adds imports (Next.js only)
`show`	Enables the development overlay
`hide`	Disables the overlay (animations are preserved)
`clearall`	Resets all animations - clears CSS file and localStorage
`help`	Shows available commands

Animation Properties

Transform Properties

Property	Range	Description
`translateX`	-1000px to 1000px	Horizontal movement
`translateY`	-1000px to 1000px	Vertical movement
`scale`	0 to 2	Size scaling
`rotate`	-360deg to 360deg	Rotation
`opacity`	0 to 1	Transparency

Timing Properties

Property	Range	Default	Description
`duration`	0-5000ms	400ms	Animation length
`delay`	0-5000ms	0ms	Start delay
`stagger`	0-500ms	0ms	Delay between children

Easing Functions

Choose from these easing functions to control how animations accelerate and decelerate:

🔘ease-out - Starts fast, ends slow
🔘ease-in - Starts slow, ends fast
🔘ease-in-out - Slow start, fast middle, slow end
🔘linear - Constant speed throughout
🔘ease - Default smoothness
🔘smooth - Extra smooth feel

Animation Triggers

Trigger	Description	Use Case
`onMount`	Animates immediately when component mounts	Page load animations
`onInView`	Animates when element enters viewport	Scroll animations
`onHover`	Animates on mouse hover	Interactive elements

Viewport Threshold (for onInView)

Configure how much of the element must be visible before the animation triggers:

🔘10% - Triggers early
🔘25% - Default, balanced
🔘50% - Half visible
🔘75% - Mostly visible
🔘100% - Fully visible

API Reference

FlomoProvider

The main component that enables Flomo. Wrap your app with it to get started.

import { FlomoProvider } from 'flomodev'

<FlomoProvider>
  {children}
</FlomoProvider>

useFlomoRef

Attach animations to a specific element in your code.

import { useFlomoRef } from 'flomodev'

function MyComponent() {
  const ref = useFlomoRef('my-element-id')
  return <div ref={ref}>This element can be animated</div>
}

How It Works

During Development

You see the Flomo overlay at the bottom of your page
Click elements to select them and create animations
See live previews as you adjust settings
Click 'Save' and animations are exported to CSS

In Production

Only the CSS file ships to your users - the Flomo overlay completely disappears. Your animations run as pure CSS with zero JavaScript overhead.

Why pure CSS? Smaller bundle size, faster load times, better performance, works everywhere.

Troubleshooting

Overlay not showing?

🔘Make sure you're in development mode (run npm run dev)
🔘Check that FlomoProvider wraps your app in layout.tsx
🔘Verify you imported flomodev/dist/index.css
🔘Try running npx flomodev show

Animations aren't saving?

🔘For Next.js: Did you run npx flomodev init?
🔘Check your browser console for red error messages
🔘Make sure your project folder is writable
🔘Try npx flomodev init again

Animations don't play after deploying?

🔘Is the CSS file imported in your production layout?
🔘Check that the CSS file actually has your animations
🔘Make sure elements have data-flomo-id attributes

AI generation not working?

🔘Check your internet connection
🔘Verify your API key is correct
🔘Look at browser console for error details

CLI commands not working?

🔘Make sure you're in your project folder
🔘Run npx flomodev help to verify it's installed

Support

Questions or feedback? Get in touch
Get API Keys: Dashboard