CSS Keyframe Animation Visualization & Debugging Library – Monorail.js

Monorail.js is a JavaScript library that converts CSS keyframe animations into interactive, visual graphs.

It extracts animation data from live CSSAnimation instances and renders them as SVG timelines with curve visualization, property tracking, and playback controls.

The library currently supports transform methods, filter functions, color properties, and any single-value numerical CSS properties.

Features:

Sponsored
• Multi-Property Analysis: Visualizes all single-value numerical CSS properties, plus dedicated parsing for transform methods (translateX, rotate, scale, etc.), filter methods (blur, brightness, contrast, etc.), and 15 color-related properties including backgroundColor, borderColor, fill, and stroke.
• Easing Curve Visualization: Renders Bézier curves between keyframes. Shows how cubic-bezier timing functions affect property transitions.
• Interactive Timeline Control: Drag to scrub through animations frame-by-frame. Click play to watch animations at configurable speeds.
• Auto-Scaled Graph Layout: Automatically calculates optimal scale factors for each property. Properties with vastly different value ranges display together in a unified view.
• Real-Time Value Inspection: Hover tooltip displays exact property values at any timeline position. Color properties show RGB/alpha values with visual swatches.
• Responsive Dark/Light Mode: Adapts to system preferences. Uses CSS custom properties for theming.

How to Use It:

1. Install Monorail.js via npm:

npm install @stanko/monorail

2. Import the library and CSS in your JavaScript file:

// Import the main Monorail class
import { Monorail } from '@stanko/monorail';

// Import required styles for the visualization UI
import '@stanko/monorail/dist/monorail.css';

3. Creating Your First Visualization

// Select the element with the animation you want to visualize
const element = document.querySelector('.animated-box');

// Get the CSSAnimation instance from the element
// getAnimations() returns an array - we grab the first animation
const animation = element.getAnimations()[0];

// Create the Monorail instance
// The constructor parses all keyframes and generates the graph
const monorail = new Monorail(animation);

// Add the visualization to your page
// monorail.element contains all UI components (graph, timeline, controls)
document.body.appendChild(monorail.element);

4. Monorail accepts an optional configuration object as the second parameter. All options have sensible defaults.

• height (number): Sets the vertical height of the SVG graph in arbitrary units. The graph auto-scales to this height regardless of property value ranges. Default is 30.
• colors (string[]): Array of CSS color values used for rendering different property curves. The library cycles through these colors for each property. Default is ['var(--monorail-purple)', 'var(--monorail-blue)', 'var(--monorail-green)', 'var(--monorail-yellow)', 'var(--monorail-orange)', 'var(--monorail-red)']. You can pass any valid CSS color strings.
• playbackSpeed (number): Multiplier for animation playback when using the play button. A value of 2 plays twice as fast, 0.5 plays at half speed. Default is 1.

5. Configuration example:

const animation = document.querySelector('.hero-animation').getAnimations()[0];

// Create visualization with custom settings
const monorail = new Monorail(animation, {
  height: 50,  // Taller graph for better readability
  colors: ['#ff0000', '#00ff00', '#0000ff'],  // Custom color scheme
  playbackSpeed: 0.5  // Slow motion playback
});

document.querySelector('#debug-panel').appendChild(monorail.element);

6. API Methods and Properties:

// Access the DOM element containing the entire visualization
// Use this to append Monorail to your page or remove it
const visualizationElement = monorail.element;
document.body.appendChild(visualizationElement);

// Change playback speed after initialization
// Accepts any positive number (0.1 for very slow, 5 for very fast)
monorail.playbackSpeed = 2;

// Clean up when you're done with the visualization
// Removes event listeners and destroys the instance
monorail.destroy();

The library intentionally exposes all internal properties and methods as public. This supports advanced use cases and experimentation during development. Be aware that modifying internal state at runtime may break interactive features like scrubbing and playback.

7. Complete integration example:

import { Monorail } from '@stanko/monorail';
import '@stanko/monorail/dist/monorail.css';

// Wait for DOM to be ready
document.addEventListener('DOMContentLoaded', () => {
  // Target element with CSS animation
  const card = document.querySelector('.pricing-card');
  
  // Get the animation instance
  const animations = card.getAnimations();
  
  // Verify animation exists before creating visualization
  if (animations.length > 0) {
    const cardAnimation = animations[0];
    
    // Create Monorail with custom configuration
    const debugger = new Monorail(cardAnimation, {
      height: 40,
      playbackSpeed: 0.75  // Slightly slower for detailed inspection
    });
    
    // Add to a specific container
    const debugPanel = document.querySelector('#animation-debug');
    debugPanel.appendChild(debugger.element);
    
    // Optional: Add cleanup on page navigation
    window.addEventListener('beforeunload', () => {
      debugger.destroy();
    });
  }
});

8. Working with multiple animations:

// Visualize multiple animations on the same element
const element = document.querySelector('.complex-component');
const animations = element.getAnimations();

// Create separate visualizations for each animation
animations.forEach((animation, index) => {
  const monorail = new Monorail(animation, {
    colors: index === 0 ? ['#ff6b6b'] : ['#4ecdc4']  // Different colors per animation
  });
  
  // Add label to distinguish animations
  const container = document.createElement('div');
  container.innerHTML = `<h4>Animation ${index + 1}: ${animation.animationName}</h4>`;
  container.appendChild(monorail.element);
  
  document.querySelector('#debug-panel').appendChild(container);
});

The post CSS Keyframe Animation Visualization & Debugging Library – Monorail.js appeared first on CSS Script.