How to Use the React Renderer for OpenMAIC Slide DSL: Complete Implementation Guide

The OpenMAIC React renderer (@openmaic/renderer) converts JSON slide DSL objects into interactive React components using SlideCanvas as the entry point, which automatically creates a rendering context and delegates DSL nodes to specialized Base...Element components.

The THU-MAIC/OpenMAIC repository provides a dedicated React renderer that transforms declarative slide DSL definitions into fully rendered presentations. By leveraging a context-based architecture in packages/@openmaic/renderer, developers can embed OpenMAIC slides into any React application using standard component patterns. This guide covers the complete implementation workflow, from basic setup to advanced customization using the renderer's source code.

Core Architecture of the OpenMAIC React Renderer

The React renderer is built around a context-driven design that separates slide data from rendering logic. Understanding these core components is essential for effective implementation.

SlideCanvas: The Entry Point

The SlideCanvas component in src/SlideCanvas.tsx serves as the primary container for all slide rendering. It creates the SlideRendererContext, handles viewport sizing, and mounts the slide element hierarchy.

When you import and use SlideCanvas, it automatically:

• Initializes the React context with your DSL object
• Calculates and monitors viewport dimensions using useViewportSize
• Iterates over the DSL children array to build the element tree
• Applies background styles via useSlideBackgroundStyle

SlideElement and Base Components

The SlideElement component in src/SlideElement.tsx acts as a generic dispatcher. It receives each DSL node from the canvas and routes it to the appropriate concrete implementation:

• BaseTextElement (src/elements/text/BaseTextElement.tsx) handles typography
• BaseImageElement (src/elements/image/BaseImageElement.tsx) renders images with clipping and filters
• StaticTable (src/elements/table/StaticTable.tsx) displays tabular data
• BaseLatexElement (src/elements/latex/BaseLatexElement.tsx) renders mathematical expressions via KaTeX

Each base component reads the node's properties—including style, layout, and animation definitions—and generates the appropriate HTML or SVG output.

React Context and State Management

The renderer uses SlideRendererContext defined in src/context.tsx as its single source of truth. This context stores:

• The current slide DSL object
• Viewport metrics (width and height)
• Utility functions for coordinate transformation

All renderer components consume this context via hooks, ensuring consistent state across the component tree. For advanced use cases, you can import SlideRendererProvider directly to wrap custom layouts.

Basic Implementation: Rendering Your First Slide

To start using the React renderer for OpenMAIC slide DSL, install the package and import the core components. The minimal implementation requires only a valid DSL object and the SlideCanvas component.

import React from 'react';
import { SlideCanvas } from '@openmaic/renderer';
import type { Slide } from '@openmaic/dsl';

const simpleSlide: Slide = {
  id: 'slide-001',
  type: 'slide',
  background: { color: '#fafafa' },
  children: [
    {
      id: 'txt-01',
      type: 'text',
      content: 'Hello OpenMAIC!',
      style: { fontSize: 48, color: '#333' },
      position: { x: 100, y: 150 },
    },
  ],
};

export default function MySlideView() {
  return (
    <div style={{ width: '100%', height: '100vh' }}>
      <SlideCanvas slide={simpleSlide} />
    </div>
  );
}

In this example, SlideCanvas creates the rendering context automatically and renders the text element via BaseTextElement, applying the font size and positioning defined in the DSL.

Working with Complex DSL Elements

The OpenMAIC React renderer supports diverse content types beyond basic text. Each element type follows the same delegation pattern but uses specialized rendering logic.

Text and Typography

Text elements use BaseTextElement to convert DSL style properties into CSS attributes. The component handles font sizing, color, alignment, and positioning defined in the element's style and position properties.

Images and Media

The BaseImageElement component in src/elements/image/BaseImageElement.tsx manages image rendering, including:

• Clipping paths defined in the DSL
• Filter effects (blur, brightness, contrast)
• Aspect ratio preservation
• Lazy loading optimizations

Tables and LaTeX

For structured data, StaticTable renders HTML tables from DSL row definitions. Mathematical content uses BaseLatexElement, which integrates KaTeX for server-side rendering of LaTeX expressions:

import { SlideCanvas } from '@openmaic/renderer';
import type { Slide } from '@openmaic/dsl';

const complexSlide: Slide = {
  id: 's2',
  type: 'slide',
  background: { color: '#ffffff' },
  children: [
    {
      id: 'tbl1',
      type: 'table',
      rows: [
        ['Metric', 'Value'],
        ['Accuracy', '94.2%'],
      ],
      style: { border: '1px solid #ddd' },
      position: { x: 50, y: 50 },
    },
    {
      id: 'latex1',
      type: 'latex',
      content: '\\sum_{i=1}^{n} x_i = \\bar{x}',
      style: { fontSize: 32 },
      position: { x: 50, y: 200 },
    },
  ],
};

export const DataSlide = () => <SlideCanvas slide={complexSlide} />;

Adding Visual Effects and Overlays

The renderer includes optional effect components for interactive presentations. These overlays attach to specific slide elements or the entire canvas.

Spotlight and Highlight Effects

Import SpotlightOverlay, LaserOverlay, or HighlightOverlay from @openmaic/renderer to add presentation effects:

import { SlideCanvas, SpotlightOverlay } from '@openmaic/renderer';

export const InteractiveSlide = ({ slide }) => (
  <>
    <SlideCanvas slide={slide} />
    <SpotlightOverlay targetId="txt-01" />
  </>
);

These components read the current viewport size from SlideRendererContext to position effects correctly relative to the target element.

Advanced: Custom Rendering Contexts

For applications requiring fine-grained control over the rendering pipeline, use the lower-level SlideRendererProvider API directly:

import {
  SlideRendererProvider,
  useSlideBackgroundStyle,
  SpotlightOverlay,
} from '@openmaic/renderer';

export const AdvancedSlideView = ({ slide }) => {
  const backgroundStyle = useSlideBackgroundStyle();

  return (
    <SlideRendererProvider slide={slide}>
      <div style={backgroundStyle}>
        <SlideCanvas />
        <SpotlightOverlay targetId="critical-element" />
      </div>
    </SlideRendererProvider>
  );
};

This pattern allows you to:

• Customize the container layout while maintaining the rendering context
• Insert additional UI elements between the provider and canvas
• Access viewport metrics via useViewportSize for responsive calculations

Key Utility Functions and Hooks

The renderer exports several utilities from src/utils/element.ts and src/utils/geometry.ts:

• useViewportSize: Returns current canvas dimensions for responsive layouts
• useSlideBackgroundStyle: Generates CSS style objects from DSL background definitions
• element.ts utilities: Convert DSL style objects into CSS/SVG attributes
• geometry.ts helpers: Handle positioning, rotation, and scaling transformations

Import these from @openmaic/renderer when building custom element implementations or external controls.

Summary

• SlideCanvas (src/SlideCanvas.tsx) is the primary entry point that creates the rendering context and handles viewport detection automatically.
• SlideElement (src/SlideElement.tsx) dispatches DSL nodes to concrete implementations like BaseTextElement, BaseImageElement, and BaseLatexElement.
• The SlideRendererContext in src/context.tsx provides a single source of truth for slide data and viewport metrics across the component tree.
• Import effect overlays such as SpotlightOverlay separately to add interactive presentation features without modifying the DSL.
• Use SlideRendererProvider directly when you need to customize the container layout or access rendering hooks like useViewportSize and useSlideBackgroundStyle.

Frequently Asked Questions

How do I install the OpenMAIC React renderer?

Install the renderer via npm or yarn using the package name @openmaic/renderer. Ensure you also install @openmaic/dsl for TypeScript type definitions. The package supports React 18+ and works with Next.js, Create React App, or Vite setups without additional configuration.

Can I render multiple slides simultaneously with SlideCanvas?

Each SlideCanvas component instance renders exactly one slide DSL object. To render multiple slides, map over your slide array and render a separate SlideCanvas for each, or implement a navigation wrapper that swaps the slide prop to switch between slides while preserving context state.

How do I customize the styling of individual DSL elements?

The React renderer applies styles defined in each DSL node's style property. For global theming, use the className prop on SlideCanvas and target elements via CSS. For dynamic styles, create a custom element wrapper that consumes useSlideBackgroundStyle or useViewportSize from the renderer's hook API to compute responsive values.

What image formats does BaseImageElement support?

BaseImageElement in src/elements/image/BaseImageElement.tsx supports standard web formats (JPEG, PNG, WebP, SVG, GIF) via standard HTML img tags or background-image CSS properties. The component handles URL loading, aspect ratio calculations, and applies DSL-defined clipping and filter effects during the render cycle.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}