Excalidraw Diagrams

Excalidraw diagrams allow you to embed interactive diagrams in your documentation. These diagrams support theme switching, fullscreen mode, and zoom controls.

Overview

Excalidraw is a virtual whiteboard for sketching hand-drawn like diagrams. You can create diagrams in Excalidraw and embed them in your documentation with full interactivity.

Features

• ✅ Theme Support: Automatically matches your website's theme (light/dark)
• ✅ Fullscreen Mode: Click the fullscreen button to view in fullscreen
• ✅ Zoom Controls: Zoom in, zoom out, and reset zoom
• ✅ Centered Display: Diagrams are automatically centered
• ✅ Responsive: Adapts to different screen sizes
• ✅ Clean UI: Default Excalidraw UI elements are hidden for a clean look

Step 1: Create Your Diagram

1. Go to Excalidraw
2. Create your diagram
3. Click the menu (three dots) → Save to file
4. Save as .excalidraw file (JSON format)

Step 2: Save the File

Save your .excalidraw file in the public/assets/docs/ directory:

Step 3: Embed in Your Content

Use the <ExcalidrawDiagram> component in your MDX:

Component Props

Required Props

• src: Path to the .excalidraw file (relative to public/)
  • Example: "/assets/docs/other/diagram.excalidraw"

Optional Props

• alt: Alt text for accessibility
  • Example: "Architecture diagram showing system components"
• caption: Caption text displayed below the diagram
  • Example: "Project Architecture Overview"
• initialZoom: Initial zoom level (default: 1 = 100%)
  • 0.5 = 50% zoom (good for large diagrams)
  • 1 = 100% zoom (default)
  • 2 = 200% zoom (for detailed diagrams)

Examples

Basic Diagram

MDX Syntax:

Rendered Result:

Here's a visual representation of the project architecture:

Diagram with Caption

MDX Syntax:

Rendered Result:

Large Diagram with Custom Zoom

MDX Syntax:

Rendered Result:

Diagram with Alt Text

MDX Syntax:

Rendered Result:

Complete Example

Here's a complete example using Excalidraw diagrams:

File Organization

Organize your Excalidraw files logically:

Zoom Levels

Choose the appropriate initial zoom level:

• initialZoom={0.5}: Good for large diagrams that need to fit on screen
• initialZoom={1}: Default - shows diagram at 100%
• initialZoom={2}: Useful for detailed diagrams that need to be larger

Controls

The diagram includes a toolbar with:

• Zoom In (+): Increase zoom level
• Zoom Out (-): Decrease zoom level
• Reset Zoom: Return to initial zoom level
• Fullscreen: View diagram in fullscreen mode

Best Practices

1. Use descriptive filenames: project-architecture.excalidraw, data-flow.excalidraw
2. Add captions: Help readers understand what the diagram shows
3. Choose appropriate zoom: Large diagrams benefit from initialZoom={0.5}
4. Organize files: Keep diagrams in logical locations (by section or topic)
5. Test both themes: Make sure diagrams look good in both light and dark modes
6. Add alt text: Improve accessibility with descriptive alt text

Troubleshooting

Diagram Not Loading

• Verify the file path is correct (relative to public/)
• Check the file exists in the specified location
• Ensure the file is valid JSON
• Check browser console for errors

Diagram Not Centered

• The diagram should automatically center on load
• If not centered, check the diagram's element positions in Excalidraw
• Try adjusting the initial zoom level

Theme Not Matching

• The diagram theme automatically matches your website theme
• If it doesn't match, check that next-themes is properly configured
• The diagram uses the same theme as the rest of your site

Next Steps

• Tabbed Content - Learn about multi-tab sections
• Images & Videos - Learn about media components
• Code Blocks - Learn about syntax highlighting