Customization

Props Overview

<ChatAnimation
  variant="phone"           // 'phone' | 'simplified' | 'minimal'
  isDarkMode={false}        // dark mode
  showAvatars={true}        // user/AI avatars
  showReactions={true}      // emoji reactions
  showReceipts={true}       // read timestamps
  showGifs={true}           // GIF images (phone only!)
  soundEnabled={false}      // sound effects
  responseStyle="dots"      // 'dots' | 'streaming' | 'instant'
  fadeMode="none"           // 'none' | 'half' (simplified/minimal only!)
  maxVisibleMessages={4}    // auto-hide older messages (simplified/minimal only!)
/>

Variants

Full iPhone with status bar, input bar, typing simulation. The one that makes people go "wait, is that real?"

<ChatAnimation variant="phone" />

GIFs and images only work in phone mode. This is the full-featured variant.

Bigger bubbles, no input bar. The chat is the star, not the phone chrome. Great for hero sections.

<ChatAnimation variant="simplified" />

Like simplified but no frame at all. Transparent background. Use this when you're embedding it in something custom.

<ChatAnimation variant="minimal" />

Some features are variant-specific. GIFs only work in phone mode. The fade effect only works in simplified/minimal. Mixing incompatible options will just silently ignore them.

Themes

Four built-in themes, each with light and dark variants:

Theme	Colors
`chatmotion`	Blue/indigo gradient (default)
`kiwi`	Green gradient
`cottoncandy`	Pink gradient
`cappuccino`	Warm brown/amber

import { getThemeColors } from '@/lib/themes';

const colors = getThemeColors('kiwi', false); // (theme, isDarkMode)

<ChatAnimation themeColors={colors} />

Custom Conversations

The default demo is fun, but you probably want your own content:

const conversations = [
  {
    question: "What can you do?",
    answer: "I can help you build amazing products!",
  },
  {
    question: "Show me",
    answer: "Here's what's possible.",
    triggerReaction: true,
    selectedReaction: "🔥",
  },
];

<ChatAnimation conversations={conversations} />

Available reaction emojis: ❤️ 👍 👎 😂 🥺 😭 🔥

You can also add images with questionImage and answerImage, but remember: images only work in phone mode.

Preset Conversations

We include two presets you can import:

import { DEFAULT_SIMPLE_CONVERSATIONS } from '@/components/chat-animation';

// 5 exchanges with existential humor
<ChatAnimation conversations={DEFAULT_SIMPLE_CONVERSATIONS} />

import { SHORT_CONVERSATIONS } from '@/components/chat-animation';

// 2 exchanges, quick demo
<ChatAnimation conversations={SHORT_CONVERSATIONS} />

The default (when you don't pass anything) uses DEFAULT_SIMPLE_CONVERSATIONS. Works great with maxVisibleMessages for longer loops.

Custom Avatars

By default, avatars are auto-generated using DiceBear (different each session). To use your own:

<ChatAnimation
  aiAvatarSrc="/images/ai-logo.png"
  userAvatarSrc="/images/user.jpg"
/>

Response Styles

<ChatAnimation responseStyle="dots" />

Typing indicator appears, then words reveal one by one. Adds natural pauses after punctuation. Periods get a longer pause than commas. It's the little things.

<ChatAnimation responseStyle="streaming" />

Fast character-by-character reveal. That ChatGPT streaming effect everyone loves.

<ChatAnimation responseStyle="instant" />

Poof, the message is there. Use this when animation would be distracting.

Sound

<ChatAnimation soundEnabled={true} />

Plays sounds on send, receive, and reaction.

Browsers block autoplay audio until the user clicks somewhere on your page. This is a browser security thing, not a bug.

The sound files are in public/sounds/. Swap them out if you want different effects:

send.mp3

receive.mp3

reaction.mp3

Controlling the Animation

Need to pause, resume, or restart?

const chatRef = useRef<ChatAnimationRef>(null);

<ChatAnimation ref={chatRef} />

// Control it:
chatRef.current?.pauseAnimation();
chatRef.current?.startAnimation();
chatRef.current?.resetAnimation();

Useful if you want to sync the animation with scroll position or user actions.

The Fade Effect

<ChatAnimation variant="simplified" fadeMode="half" pageDarkMode={false} />

Adds a gradient fade at the bottom. Looks great when the chat floats above other content. Set pageDarkMode to match your page background so the fade blends correctly.

Only works in simplified and minimal modes. Phone mode has an input bar at the bottom so fading would look weird.

Conversation Length & Scrolling

Simplified/minimal modes handle overflow automatically:

`maxVisibleMessages`	Behavior
Not set	Shows 2 complete exchanges (4 messages), then stops. Safe default.
Set to N	Shows full conversation. Only last N messages visible, older ones fade out.

// Stops after 4 messages (2 exchanges)
<ChatAnimation variant="minimal" />

No overflow, no scrolling. The animation stops after 4 messages.

// Full conversation, last 4 visible
<ChatAnimation variant="minimal" maxVisibleMessages={4} />

Shows the full conversation with older messages fading out as new ones appear.

Phone mode has its own scroll container, so maxVisibleMessages is intentionally ignored there. You can still pass it (won't break anything), but it won't do anything.

Create a custom theme

On this page