feat: Add optional block animation support

[coderpr0grammer]

Description

Add optional animate and animationDuration props to enable progressive fade-in animation on streaming blocks. Uses pure CSS with staggered nth-child delays - no DOM structure changes, Block component stays untouched.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Performance improvement
• Refactoring (no functional changes)

Related Issues

Related to streaming UX improvements

Changes Made

• Add animate?: boolean prop to StreamdownProps (default: false)
• Add animationDuration?: number prop to StreamdownProps (default: 300ms)
• Add CSS keyframes injection function that runs only when animate=true
• Apply .streamdown-animate class to container with staggered nth-child animation delays
• Add prefers-reduced-motion media query support for accessibility
• Update memo comparison to include new animation props

Code Changes

Animation CSS and injection (added after imports):

// Animation CSS - injected only when animate=true
const animationCSS = `
@keyframes streamdownFadeIn {
  from { opacity: 0; }
  to { opacity: 1; }
}
.streamdown-animate > * {
  animation: streamdownFadeIn var(--streamdown-duration, 300ms) ease-out both;
  opacity: 0;
}
.streamdown-animate > *:nth-child(1) { animation-delay: 0ms; }
.streamdown-animate > *:nth-child(2) { animation-delay: 60ms; }
.streamdown-animate > *:nth-child(3) { animation-delay: 120ms; }
.streamdown-animate > *:nth-child(4) { animation-delay: 180ms; }
.streamdown-animate > *:nth-child(n+5) { animation-delay: 240ms; }
@media (prefers-reduced-motion: reduce) {
  .streamdown-animate > * {
    animation: none !important;
    opacity: 1 !important;
  }
}
`;

let animationStylesInjected = false;
function injectAnimationStyles() {
  if (animationStylesInjected || typeof document === "undefined") return;
  const styleId = "streamdown-animation";
  if (document.getElementById(styleId)) {
    animationStylesInjected = true;
    return;
  }
  const el = document.createElement("style");
  el.id = styleId;
  el.textContent = animationCSS;
  document.head.appendChild(el);
  animationStylesInjected = true;
}

Props added to StreamdownProps:

export type StreamdownProps = Options & {
  // ... existing props ...
  /** Enable simple fade-in animation on blocks */
  animate?: boolean;
  /** Fade-in animation duration in ms (default: 300) */
  animationDuration?: number;
};

useEffect to inject styles:

// Inject animation CSS when animate is enabled
useEffect(() => {
  if (animate) {
    injectAnimationStyles();
  }
}, [animate]);

Container div with conditional class and style:

<div
  className={cn(
    "space-y-4 whitespace-normal *:first:mt-0 *:last:mb-0",
    animate && "streamdown-animate",
    className
  )}
  style={
    animate
      ? ({ "--streamdown-duration": `${animationDuration}ms` } as React.CSSProperties)
      : undefined
  }
>

Testing

• All existing tests pass
• Added new tests for the changes
• Manually tested the changes

Test Coverage

Manually tested with:

• Streaming content with animation enabled
• Static content with animation enabled
• Animation disabled (default behavior unchanged)
• Various animation durations (200ms, 350ms, 500ms)
• LaTeX/KaTeX rendering with animation
• Code blocks with syntax highlighting
• Mermaid diagrams

Screenshots/Demos

Checklist

• My code follows the project's code style
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings or errors
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have created a changeset (pnpm changeset)

Changeset

• I have created a changeset for these changes

Additional Notes

Usage

<Streamdown animate={true} animationDuration={350}>
  {streamingContent}
</Streamdown>

Design Decisions

1. Pure CSS approach: Animation is handled entirely via CSS keyframes and classes, avoiding any JavaScript animation libraries or DOM manipulation.

2. Style injection: CSS is injected into the document head only when animate=true, keeping the default bundle size unchanged for users who don't use animation.

3. Staggered delays: First 4 blocks get progressively longer delays (0ms, 60ms, 120ms, 180ms), then all subsequent blocks use 240ms to prevent excessive delays on long content.

4. Accessibility: Includes prefers-reduced-motion media query to respect user preferences and disable animations for users who have motion sensitivity.

5. No breaking changes: All existing functionality remains unchanged. Animation is opt-in via the animate prop (default: false).

Compatibility

• Works with all existing features (LaTeX, code blocks, Mermaid, tables, images)
• Compatible with the caret prop for cursor indicator
• Works in both streaming and static modes

[haydenbleasel]

Added animations in #371