Excaliframe

Excaliframe brings animated diagrams and auto-export to Excalidraw in VS Code. Create stunning animated visualizations that export automatically to SVG—perfect for documentation, blog posts, and presentations.

powered by Excalidraw.

(- Made with Excaliframe ;-) -

✨ Features

🎬 Animate Your Drawings

• Animation Types:
  • Draw: Elements animate stroke-by-stroke as if being hand-drawn
  • Fade: Elements fade in smoothly over time
  • None: No animation (static elements)
• Visual Timeline Control: drag-and-drop interface for managing animation sequences
• Per-Element Timing: Control start time and duration for each element
• Real-time Preview: See your animations come to life as you edit

📦 Auto-Export Frames

• Automatic SVG Export: Files update as you edit—no manual export step needed!
• Dual Theme Support: Exports both light and dark versions automatically
• Static & Animated Versions:
  • {framename}.stat.light.exp.svg - static light version
  • {framename}.stat.dark.exp.svg - static dark version
  • {framename}.anim.light.exp.svg - animated light version (if frame has animated elements)
  • {framename}.anim.dark.exp.svg - animated dark version (if frame has animated elements)
• Smart Frame Detection: Automatically exports frames marked for export
• Debounced Updates: Configurable delay prevents excessive file writes

🎨 Frame Management

• Random Frame Naming: Auto-generates memorable names (e.g., jumping__horse, running__dog)
• Export Toggle: Mark any frame for export with a single click
• Frame References: Open .exp.svg files to view exports alongside your source
• Path Support: Use relative paths, parent directories (../), or absolute paths in frame names

💎 Watermark & Licensing

• Free with Attribution: "Made with Excaliframe" watermark on bottom-right of exports
• Supporter License: Remove watermarks with a license key - comming soon

🌐 Full Excalidraw Integration

• Complete Editing: All Excalidraw features available (shapes, arrows, text, images, etc.)
• Library Support: Save and reuse library items across diagrams
• Theme Sync: Auto/light/dark theme options that sync with VS Code
• File Formats: Open .excalidraw, .excalidraw.svg, and .excalidraw.png files

🌟 Showcase

See Excaliframe in action! Check out real-world examples:

• SQLite on Git - Part 2 - Animated diagrams demonstrating SQLite architecture and workflow, showcasing Excaliframe's auto-export and animation features in a technical blog post.

Have you used Excaliframe in your project? Share it and we'll feature it here!

🚀 Quick Start

Installation

From VS Code Marketplace

1. Open VS Code
2. Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X)
3. Search for "Excaliframe"
4. Click Install

Creating Your First Animated Diagram

1. Create a new file: Use the Command Palette (Cmd+Shift+P) and run "Excalidraw: New File"

2. Draw your diagram: Use Excalidraw's tools to create shapes, arrows, text, etc.

3. Create a frame:

   • Select the elements you want to animate
   • Click the frame icon in the toolbar or press Ctrl/Cmd + Shift + F
   • The frame gets a random name like jumping__horse

4. Enable export:

   • Select the frame
   • In the Animate panel, toggle the "Export" switch
   • SVG files are automatically created in the same directory

5. Add animations:

   • Select elements within the frame
   • In the Animate panel properties:
     • Animation Type: Choose Draw, Fade, or None
     • Start: When animation begins (in milliseconds)
     • Duration: How long the animation lasts (in milliseconds)
   • Use the timeline to visually adjust timing

6. Preview your animation:

   • Click the play icon in the Animate panel header
   • Hover over exports to see animated preview
   • Adjust timing in the timeline with drag-and-drop

7. Use in Markdown:

![My diagram - dark](https://github.com/martin-lysk/excalidraw-vscode/raw/HEAD/jumping__horse.anim.dark.exp.svg#gh-dark-mode-only)
![My diagram - light](https://github.com/martin-lysk/excalidraw-vscode/raw/HEAD/jumping__horse.anim.light.exp.svg#gh-light-mode-only)

The images update instantly when you modify the frame!

📖 Usage Guide

Animation Panel

The Animation Panel has two tabs:

Frames Tab

• Frame List: See all frames in your diagram
• Export Toggle: Click to enable/disable auto-export for each frame
• Animate Toggle: Enable animation for the entire frame
• Frame Name: Click to edit (supports paths like ../exports/animation)

Properties Tab

Configure animation for selected elements:

• Animation Type: Choose from Draw, Fade, or None
• Start Time: When the element animation begins (ms)
• Duration: How long the animation lasts (ms)
• Watermark Position: Choose watermark placement (requires license for "none")

Timeline Controls

• Select: Click elements in the timeline to select them in the diagram
• Move: Drag elements left/right to change start time
• Resize: Drag edges to adjust duration
• Zoom: Use +/- buttons to zoom in/out for precise control
• Fit: Toggle auto-fit to show all elements
• Multi-Row: Elements can be assigned to different rows for organization

Animation Types Explained

1. Draw (✏️)

   • Elements animate stroke-by-stroke as if being drawn by hand
   • Works best with: lines, arrows, rectangles, ellipses
   • Creates a hand-drawn feel

2. Fade (〰️)

   • Elements smoothly fade in from transparent to opaque
   • Works with all element types
   • Great for: text, grouped elements, complex shapes

3. None (⃠)

   • No animation - element appears immediately
   • Good for: static backgrounds, labels, reference elements
   • Can be mixed with animated elements in the same frame

Export File Naming

Files are named using the pattern: {framename}.{type}.{theme}.exp.svg

• framename: Randomly generated verb__animal (e.g., jumping__horse) or custom
• type: stat (static) or anim (animated)
• theme: light or dark

Example exports:

jumping__horse.stat.light.exp.svg
jumping__horse.stat.dark.exp.svg
jumping__horse.anim.light.exp.svg  (only if frame has animated elements)
jumping__horse.anim.dark.exp.svg  (only if frame has animated elements)

Working with Exports

Viewing Exports

• Any .exp.svg file opens in the Frame Reference viewer
• Shows both static and animated versions
• Theme-aware (respects VS Code theme)

Using in Documentation

GitHub/GitLab Markdown:

![Diagram](https://github.com/martin-lysk/excalidraw-vscode/raw/HEAD/animation.anim.light.exp. svg#gh-light-mode-only)
![Diagram](https://github.com/martin-lysk/excalidraw-vscode/raw/HEAD/animation.anim.dark.exp. svg#gh-dark-mode-only)

HTML:

<picture>
  <source srcset="./animation.anim.dark.exp. svg" media="(prefers-color-scheme: dark)">
  <img src="https://github.com/martin-lysk/excalidraw-vscode/raw/HEAD/animation.anim.light.exp. svg" alt="Diagram">
</picture>

VS Code Markdown:

![Diagram](https://github.com/martin-lysk/excalidraw-vscode/raw/HEAD/animation.anim.exp. svg)

(Uses the default theme version)

⚙️ Configuration

Excaliframe can be configured via VS Code settings:

{
  // Theme (default: "light")
  "excaliframe.theme": "auto",  // "auto", "light", or "dark"

  // Language (default: VS Code display language)
  "excaliframe.language": "en",

  // Workspace library path
  "excaliframe.workspaceLibraryPath": "library.excalidrawlib",

  // Image export settings
  "excaliframe.image": {
    "exportScale": 1,              // 1, 2, or 3
    "exportWithBackground": true,
    "exportWithDarkMode": false
  },

  // Frame export debounce delay (ms)
  "excalidraw.frameExportDebounce": 500,

  // Supporter license key (removes watermark)
  "excaliframe.licenseKey": "your-license-key-here"
}

Settings Explained

• theme: Controls Excaliframe's color theme

  • auto: Syncs with VS Code's theme
  • light: Always light theme
  • dark: Always dark theme

• language: UI language (supports 30+ languages)

• workspaceLibraryPath: Path to library file (relative to workspace root)

• image.exportScale: Resolution multiplier for embedded images

  • 1: Standard resolution
  • 2: 2x resolution (sharper, larger files)
  • 3: 3x resolution (very sharp, largest files)

• frameExportDebounce: Delay (ms) before re-exporting after changes

  • Lower = more responsive but more file writes
  • Higher = fewer writes but less responsive
  • Recommended: 300-1000ms

• licenseKey: Supporter license to remove watermarks

💡 Tips & Tricks

Frame Organization

1. Use descriptive names: Double-click frame name to edit

   tutorials/installation/process.diagram
   ../assets/logo.animation
   

2. Group related elements: Put related animations in the same frame

3. Layer frames: Use multiple frames for complex diagrams

Animation Best Practices

1. Start simple: Begin with one or two animated elements

2. Use the timeline: Visual feedback helps understand timing

3. Mix animation types:

   • Use Draw for outlines and arrows
   • Use Fade for text and filled shapes
   • Use None for backgrounds

4. Duration guidelines:

   • Quick accents: 200-400ms
   • Standard animations: 500-800ms
   • Complex reveals: 1000-1500ms

5. Stagger elements: Offset start times for sequential effects

   • Element 1: 0ms
   • Element 2: 200ms
   • Element 3: 400ms

Performance Tips

1. Limit frame size: Very large frames (>50 elements) may slow down

2. Use debounce: Increase frameExportDebounce if editing feels sluggish

3. Export selectively: Only toggle "Export" on frames you need

Common Workflows

Creating a Tutorial Diagram

1. Create frame: `tutorial/step1.setup`
2. Add static background elements (animation: none)
3. Add first action (animation: draw, start: 0ms)
4. Add explanation (animation: fade, start: 500ms)
5. Export and use in documentation

Logo Animation

1. Import or draw logo
2. Wrap in frame: `assets/logo.anim`
3. Animate strokes (draw) then fills (fade)
4. Export for web use

Architecture Diagram

1. Create base diagram frame (static)
2. Create overlay frame for flow (animated)
3. Combine in markdown with different themes

🆚 Differences from Excalidraw VSCode

Excaliframe adds these features to the base excalidraw-vscode extension:

• ✅ Animation System: Timeline-based animations with multiple types
• ✅ Auto-Export: Automatic SVG export on file changes
• ✅ Frame Management: Enhanced frame naming, export toggles, references
• ✅ Dual-Theme Export: Light and dark versions generated automatically
• ✅ Watermark System: Optional watermarks with supporter licensing
• ✅ Preview System: Live preview with interactive watermark removal
• ✅ SMIL Animations: Exported SVGs include SMIL animation data

🙏 Credits

This extension is a fork of the excellent excalidraw-vscode by pomdtr, which integrates Excalidraw into VS Code.

📝 License

Same as the original excalidraw-vscode project.

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests on GitHub.

📮 Support

• Issues: GitHub Issues
• License: Get a supporter license at excaliframe.lysk.tech
• Updates: Follow the project on GitHub for updates

Made with ❤️ by Martin Lysk