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

> Learn to use the React renderer for OpenMAIC slide DSL. This guide details implementing `@openmaic/renderer` to convert JSON DSL into interactive React components with SlideCanvas.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: how-to-guide
- Published: 2026-08-31

---

**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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src/elements/text/BaseTextElement.tsx)) handles typography
- `BaseImageElement` ([`src/elements/image/BaseImageElement.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src/elements/image/BaseImageElement.tsx)) renders images with clipping and filters
- `StaticTable` ([`src/elements/table/StaticTable.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src/elements/table/StaticTable.tsx)) displays tabular data
- `BaseLatexElement` ([`src/elements/latex/BaseLatexElement.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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.

```tsx
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

```tsx
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:

```tsx
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:

```tsx
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src/utils/element.ts) and [`src/utils/geometry.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src/utils/geometry.ts):

- **`useViewportSize`**: Returns current canvas dimensions for responsive layouts
- **`useSlideBackgroundStyle`**: Generates CSS style objects from DSL background definitions
- **[`element.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/element.ts) utilities**: Convert DSL style objects into CSS/SVG attributes
- **[`geometry.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src/SlideCanvas.tsx)) is the primary entry point that creates the rendering context and handles viewport detection automatically.
- **SlideElement** ([`src/SlideElement.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/src/SlideElement.tsx)) dispatches DSL nodes to concrete implementations like `BaseTextElement`, `BaseImageElement`, and `BaseLatexElement`.
- The **SlideRendererContext** in [`src/context.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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.