reveal.js -- Administrator & Developer Guide

reveal.js v6.0.1 is a JavaScript presentation framework that transforms semantic HTML into fully interactive slide decks with transitions, fragments, speaker notes, code highlighting, math rendering, and more. This guide covers every architectural detail, configuration option, and operational concern an administrator or developer needs to deploy, extend, customize, and maintain reveal.js presentations at any scale.

For installation walkthroughs, everyday usage, and feature tutorials, see the User Guide.

1. Architecture Overview

1.1 Design Philosophy

reveal.js uses a closure-based factory pattern rather than ES6 classes. The main entry point (js/reveal.js) exports a factory function that returns a Reveal object. Each presentation instance is a self-contained closure with private state and a public API surface. This enables multiple independent presentations on a single page without shared mutable state.

The framework has zero runtime dependencies. Every dependency in package.json is a devDependency used only during build time. The distributed bundle is fully self-contained.

1.2 Entry Point and Initialization Flow

The initialization sequence proceeds through these stages:

1. Factory invocation -- Reveal() or new Reveal() creates a presentation instance
2. Config merge -- defaultConfig from js/config.ts is merged with constructor options
3. DOM validation -- locates the .reveal root element (throws "Unable to find presentation root (<div class="reveal">)" if missing)
4. Controller instantiation -- all 20 internal controllers are created
5. Plugin registration -- plugins from config.plugins array are registered
6. Plugin initialization -- all plugins' init() methods are called and awaited
7. Layout -- initial layout calculation and slide positioning
8. ready event -- fires only after all plugins have initialized

Important

The ready event is the only safe point to begin interacting with the API programmatically. Code that runs before ready may encounter uninitialized plugins or incomplete DOM state.

1.3 Controller Inventory

Every controller is instantiated during initialization and manages a specific aspect of the presentation. Controllers communicate through the central Reveal instance and its event system.

1.4 Module Dependency Graph

reveal.js (factory)
  +-- config.ts (defaults + RevealConfig interface)
  +-- controllers/ (20 controllers)
  |     +-- plugins.js --> plugin instances
  |     +-- slidecontent.js --> utils/loader.ts
  |     +-- autoanimate.js --> utils/util.ts
  |     +-- location.js --> utils/util.ts (getQueryHash)
  |     +-- backgrounds.js --> utils/color.ts
  +-- utils/
  |     +-- color.ts (colorToRgb, colorBrightness)
  |     +-- constants.ts (selectors, blacklists, regex)
  |     +-- device.ts (isMobile, isChrome, isAndroid)
  |     +-- loader.ts (dynamic script/link injection)
  |     +-- util.ts (DOM helpers, math, serialization)
  +-- components/
        +-- playback.js (canvas UI)

1.5 Utility Modules

2. System Requirements

2.1 Build Environment

2.2 Build Toolchain (devDependencies)

All dependencies are development-only. The built output has zero runtime dependencies.

2.3 Browser Support

reveal.js targets modern browsers with ES module support. The npm run build:es5 command produces an ES5 fallback bundle via esbuild for legacy environments.

Note

Device detection in js/utils/device.ts applies browser-specific workarounds. The isChrome and isAndroid flags affect touch handling and rendering behavior.

2.4 React Wrapper Requirements

The @revealjs/react package (v0.2.1) in react/ has these peer dependencies:

3. Configuration Reference

3.1 Config Resolution Order

Configuration values are merged with increasing precedence:

1. defaultConfig -- hardcoded defaults in js/config.ts
2. Reveal.configure() calls before initialize() -- pre-init overrides
3. Constructor options -- Reveal({ ... }) or new Reveal({ ... })
4. Reveal.initialize() options -- final programmatic overrides
5. URL query parameters -- parsed by getQueryHash() from the URL fragment

Tip

URL query parameters provide an easy way to override config for testing or sharing. Append them after # in the URL: presentation.html#/2?transition=none&controls=false. Values are automatically deserialized (strings "true"/"false" become booleans, numeric strings become numbers).

3.2 Complete Config Options

Every option below is from the defaultConfig object in js/config.ts and the RevealConfig interface.

3.2.1 Presentation Dimensions

3.2.2 Controls

3.2.3 Progress and Slide Numbers

3.2.4 Navigation and History

3.2.5 Content Behavior

3.2.6 Media and Embedding

3.2.7 Appearance

3.2.8 Auto-Animate

3.2.9 Auto-Slide

3.2.10 Transitions

3.2.11 Parallax Backgrounds

3.2.12 Scroll View

3.2.13 PDF Export

3.2.14 Plugins and PostMessage

3.3 Plugin-Specific Config Keys

Plugin configuration is nested under the main config object using the plugin name as the key.

3.3.1 Highlight Plugin Config

Reveal.initialize({
  highlight: {
    highlightOnLoad: true,    // boolean - Auto-highlight <pre><code> on load
    escapeHTML: true,          // boolean - Escape HTML entities in code blocks
    beforeHighlight: null      // function(code, block) - Callback before highlighting
  }
});

3.3.2 Markdown Plugin Config

Reveal.initialize({
  markdown: {
    separator: '\\r?\\n---\\r?\\n',       // string - Horizontal slide separator regex
    verticalSeparator: null,               // string|null - Vertical slide separator regex
    notesSeparator: '^\\s*notes?:',        // string - Notes separator regex
    animateLists: false,                   // boolean - Wrap <li> elements in fragments
    smartypants: false,                    // boolean - Enable typographic quote replacement
    // All marked library options are also accepted:
    gfm: true,                            // boolean - GitHub Flavored Markdown
    breaks: false,                         // boolean - Treat newlines as <br>
    renderer: null                         // object - Custom marked renderer
  }
});

3.3.3 Math Plugin Config (KaTeX)

Reveal.initialize({
  katex: {
    local: null,              // string|null - Path to local KaTeX installation
    version: 'latest',        // string - KaTeX version from CDN
    delimiters: [             // array - Delimiter pairs for math detection
      { left: '$$', right: '$$', display: true },
      { left: '$', right: '$', display: false },
      { left: '\\(', right: '\\)', display: false },
      { left: '\\[', right: '\\]', display: true }
    ],
    ignoredTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
    extensions: []            // array - KaTeX extensions (e.g., ['mhchem'])
  }
});

CDN base: cdn.jsdelivr.net/npm/katex

3.3.4 Math Plugin Config (MathJax2)

Reveal.initialize({
  mathjax2: {
    mathjax: 'https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js',
    config: 'TeX-AMS_HTML-full',    // string - MathJax configuration preset
    tex2jax: {
      inlineMath: [['$', '$'], ['\\(', '\\)']],
      skipTags: ['script', 'noscript', 'style', 'textarea', 'pre']
    }
  }
});

MathJax2 retypesets on every slidechanged event.

3.3.5 Math Plugin Config (MathJax3)

Reveal.initialize({
  mathjax3: {
    mathjax: 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js',
    tex: {
      inlineMath: [['$', '$'], ['\\(', '\\)']]
    },
    options: {
      skipHtmlTags: ['script', 'noscript', 'style', 'textarea', 'pre']
    },
    startup: {
      ready: null              // function - Custom startup handler
    }
  }
});

Sets window.MathJax configuration object before loading the library.

3.3.6 Math Plugin Config (MathJax4)

Reveal.initialize({
  mathjax4: {
    mathjax: 'https://cdn.jsdelivr.net/npm/mathjax@4/tex-mml-chtml.js',
    tex: {
      inlineMath: [['$', '$'], ['\\(', '\\)']]
    },
    options: {
      skipHtmlTags: ['script', 'noscript', 'style', 'textarea', 'pre']
    },
    startup: {
      ready: null
    },
    output: 'chtml'            // string - Output format
  }
});

Uses async startup and waits for MathJax.startup.promise to resolve.

4. Deployment & Scaling

4.1 Build Commands

4.2 Build Architecture

Each plugin has its own vite.config.ts that produces both ES module (.mjs) and UMD (.js) formats. TypeScript declarations are generated via vite-plugin-dts with a custom path rewriting plugin at plugin/vite-plugin-dts.ts.

The build pipeline:

TypeScript compile (tsc)
  +-- Vite build: core (js/index.ts -> dist/reveal.{js,mjs})
  +-- Vite build: highlight plugin (-> dist/plugin/highlight.{js,mjs})
  +-- Vite build: markdown plugin (-> dist/plugin/markdown.{js,mjs})
  +-- Vite build: math plugin (-> dist/plugin/math.{js,mjs})
  +-- Vite build: notes plugin (-> dist/plugin/notes.{js,mjs})
  +-- Vite build: search plugin (-> dist/plugin/search.{js,mjs})
  +-- Vite build: zoom plugin (-> dist/plugin/zoom.{js,mjs})
  +-- Sass compile: themes (css/theme/*.scss -> dist/theme/*.css)
  +-- Sass compile: base (css/reveal.scss -> dist/reveal.css)
  +-- Copy: reset.css -> dist/reset.css

4.3 Package Exports Map

The package.json exports field defines the public module entry points:

4.4 Deployment Patterns

Static File Hosting

The simplest deployment is serving the dist/ directory (plus your HTML files) from any static host (Nginx, Apache, S3, Netlify, Vercel, GitHub Pages).

your-presentation/
  index.html
  dist/
    reveal.js
    reveal.mjs
    reveal.css
    reset.css
    theme/
    plugin/

CDN Usage

Warning

As of v6.0.1, CDN availability is a known issue (see GitHub issue #3894). Verify the version is available on your CDN of choice before relying on it for production.

npm Package

import Reveal from 'reveal.js';
import 'reveal.js/reveal.css';
import 'reveal.js/theme/black.css';
import Highlight from 'reveal.js/plugin/highlight';
import Markdown from 'reveal.js/plugin/markdown';

Self-Hosted with Vite Dev Server

For development, npm run dev starts Vite with hot module replacement. The index.html at the project root serves as the development entry point.

4.5 Multiple Instances

reveal.js supports multiple independent presentation instances on a single page. Each Reveal() call creates a new instance targeting a different .reveal root element:

let deck1 = new Reveal(document.querySelector('#deck1'), { embedded: true });
let deck2 = new Reveal(document.querySelector('#deck2'), { embedded: true });

await deck1.initialize();
await deck2.initialize();

Set embedded: true to prevent instances from capturing global keyboard events.

Caution

When running multiple instances, each must target a unique DOM element. Initializing two instances on the same .reveal root leads to undefined behavior. The embedded: true flag is essential to prevent keyboard/focus conflicts.

5. Operations

5.1 Theme System

reveal.js ships 14 themes, all authored as SCSS in css/theme/:

Theme Architecture

The theme template system uses three files in css/theme/template/:

• settings.scss -- Defines all SCSS variables (fonts, colors, spacing, heading sizes)
• mixins.scss -- Shared SCSS mixins
• theme.scss -- Base theme styles that consume the variables

Each theme file imports the template, overrides variables, and optionally adds custom rules. To create a custom theme:

// my-theme.scss
@use 'template/settings' with (
  $backgroundColor: #191919,
  $mainColor: #fff,
  $headingColor: #fff,
  $linkColor: #42affa
);
@use 'template/theme';

5.2 PDF Export

PDF export works through the PrintView controller. Access the print-optimized layout by appending ?print-pdf to the URL, then use the browser's print dialog (Ctrl/Cmd+P).

Key config options:

• pdfSeparateFragments: true -- each fragment step gets its own page
• pdfMaxPagesPerSlide: Infinity -- limit pages for very tall slides
• pdfPageHeightOffset: -1 -- auto-detect page height offset

The pdf-ready event fires when the print layout is fully rendered and ready for capture.

Note

GitHub issue #3860 reports that PDF export can generate very large files. Issue #3888 documents compatibility problems with Decktape (a popular third-party PDF export tool). For reliable PDF export, use the browser's native print dialog with Chrome.

5.3 Keyboard Shortcuts

Default key bindings registered by the Keyboard controller:

5.4 Events Reference

All events are dispatched via the reveal.js event system and can be listened to with Reveal.on():

6. Performance

6.1 Lazy Loading

The SlideContent controller implements lazy loading based on viewDistance (default: 3 slides) and mobileViewDistance (default: 2). Content outside the view distance is not loaded until the user navigates near it.

This affects:

• <img> with data-src -- source set on approach, cleared on departure
• <video> and <audio> with data-src -- source set on approach
• <iframe> with data-src -- source set on approach, cleared on departure
• Background images, videos, and iframes follow the same pattern

6.2 Layout Performance

• layout() recalculates all slide positions and scaling. Called automatically on window resize.
• sync() re-processes all slides (content, backgrounds, fragments). Expensive; use syncSlide() for single-slide updates.
• disableLayout: true skips all reveal.js layout calculations, deferring entirely to CSS.
• Background brightness detection (colorBrightness() in utils/color.ts) adds has-light-background or has-dark-background classes, enabling automatic text color adaptation.

6.3 Mobile Optimization

• mobileViewDistance reduces preloading on mobile to conserve bandwidth and memory
• Touch controller uses passive event listeners where supported
• Device detection (utils/device.ts) adjusts behavior for mobile browsers
• scrollActivationWidth: 435 auto-activates scroll view on narrow viewports

Tip

For bandwidth-constrained deployments, reduce viewDistance and mobileViewDistance to 1. This significantly reduces upfront resource loading at the cost of brief loading delays during navigation.

7. Security

7.1 PostMessage API Security

The postMessage API enables cross-window communication (used by the speaker notes window and embedded presentations). Security measures:

Method Blacklist (POST_MESSAGE_METHOD_BLACKLIST in js/utils/constants.ts):

The following methods are blocked from postMessage invocation to prevent unauthorized plugin injection, event hijacking, and preview abuse:

• registerPlugin
• registerKeyboardShortcut
• addKeyBinding
• addEventListener
• showPreview
• previewIframe

Any postMessage attempting to call these methods is silently ignored.

7.2 Speaker Notes Window Security

The Notes plugin implements same-origin verification on postMessage events. Only messages from the same origin (window.location.origin) are accepted. This XSS safeguard prevents malicious cross-origin pages from injecting commands into the speaker view.

The notes window uses a heartbeat mechanism for orphaned window reconnection -- if the parent window closes and reopens, the existing notes window can re-establish the connection.

7.3 Query Parameter Sanitization

The getQueryHash() function in js/utils/util.ts explicitly deletes the dependencies key from parsed URL query parameters. This prevents script injection via crafted URLs that could load arbitrary remote scripts through the legacy dependency system.

7.4 Markdown External File Loading

External markdown files loaded via <section data-markdown="file.md"> use XHR requests, which are subject to the browser's same-origin policy. Cross-origin markdown files require appropriate CORS headers on the serving host.

Warning

When postMessage: true (the default), any page that can reference your presentation's window can send navigation commands. Set postMessage: false for presentations containing sensitive content that should not be externally controllable.

7.5 Content Security Policy Considerations

reveal.js dynamically creates <style> elements (via createStyleSheet() in utils/util.ts) and injects inline styles for layout. A strict CSP policy requires:

• style-src 'unsafe-inline' -- for dynamic style injection
• script-src must allow the reveal.js bundle and any plugin scripts
• frame-src as needed for iframe backgrounds and preview overlays
• Math plugins load scripts from cdn.jsdelivr.net by default; either allow this origin or use the local config option

8. Developer Internals

8.1 Plugin Architecture

Plugin Interface

interface RevealPlugin {
  id: string;                              // Unique identifier
  init?(reveal: RevealApi): void | Promise<void>;  // Called during initialization
  destroy?(): void;                        // Called on Reveal.destroy()
}

Plugins can also be registered as factory functions that return a RevealPlugin object:

// Factory pattern
const MyPlugin = () => ({
  id: 'my-plugin',
  init: (reveal) => {
    // Access full API
    reveal.on('slidechanged', handleSlideChange);
    reveal.getConfig(); // read config
  },
  destroy: () => {
    // Cleanup
  }
});

Reveal.initialize({
  plugins: [MyPlugin]
});

Plugin Lifecycle

1. Registration -- plugins are registered from config.plugins array or via Reveal.registerPlugin(plugin)
2. Initialization -- Plugins controller calls each plugin's init() method, passing the RevealApi instance
3. Async support -- if init() returns a Promise, the framework waits for all plugin promises to resolve before firing ready
4. Access -- Reveal.hasPlugin(id), Reveal.getPlugin(id), Reveal.getPlugins() for runtime inspection
5. Destruction -- Reveal.destroy() calls each plugin's destroy() method

Built-in Plugin Details

Highlight (id: 'highlight')

• Wraps highlight.js for syntax highlighting
• Processes all <pre><code> blocks in the presentation
• data-line-numbers attribute format: "1,2|3,5-10" where | separates animation steps, , separates individual lines, - denotes ranges
• data-trim normalizes leading/trailing whitespace
• data-noescape prevents HTML entity escaping
• data-fragment-index controls fragment ordering when line highlighting steps

Markdown (id: 'markdown')

• Wraps marked library with marked-smartypants extension
• Two authoring modes:
  • Inline: <section data-markdown> with <script type="text/template"> or <textarea data-template>
  • External: <section data-markdown="file.md"> loads via XHR
• Attribute injection via HTML comments:
  • Element: <!-- .element: class="fragment" data-fragment-index="1" -->
  • Slide: <!-- .slide: data-background="#ff0000" -->
• Default separators: horizontal \r?\n---\r?\n, vertical null, notes ^\s*notes?:

Math (wrapper, id depends on sub-plugin)

• Contains 4 sub-plugins: KaTeX (id: 'katex'), MathJax2 (id: 'mathjax2'), MathJax3 (id: 'mathjax3'), MathJax4 (id: 'mathjax4')
• MathJax2 is the default if Math is registered without specifying a sub-plugin
• Each sub-plugin loads its library from CDN by default but supports local paths

Notes (id: 'notes')

• Opens speaker view in a popup window (triggered by S key, keyCode 83)
• Communication via postMessage with same-origin check
• Notes sources (in priority order): fragment-level notes override slide-level
  • <aside class="notes"> elements
  • data-notes attribute on <section>
• Heartbeat for orphaned window reconnection

Search (id: 'search')

• Registers Ctrl+Shift+F keyboard shortcut
• Uses Hilitor algorithm for DOM-based text highlighting
• Highlight colors cycle: #ff6, #a0ffff, #9f9, #f99, #f6f
• Methods: open(), close(), toggle()
• Input field appears top-right, Enter advances to next match

Zoom (id: 'zoom')

• Alt+Click to zoom (Ctrl+Click on Linux)
• Config: zoomKey (override modifier key), zoomLevel (default: 2)
• Escape to zoom out
• CSS transform-based with mouse-tracking pan support
• Methods: zoom.to(), zoom.out(), zoom.magnify(), zoom.reset(), zoom.zoomLevel()

8.2 Public API Reference

The complete public API as defined in reveal.d.ts:

Initialization and Lifecycle

Navigation

State

Slide Access

Queries

Toggles

Plugins

Keyboard

Events

Preview

8.3 Data Attributes Reference

Slide-Level Attributes

Background Attributes

Auto-Animate Attributes

Fragment Animations

Applied as CSS classes on elements with class="fragment":

Custom animation classes are also supported -- any string value works and is applied as a CSS class.

Tip

Fragment order is controlled by data-fragment-index. Multiple elements can share the same index to animate simultaneously. When sortFragmentsOnSync is true (default), fragments are automatically sorted by their index.

8.4 Error Messages

8.5 Test Infrastructure

Test HTML pages in test/ cover: auto-animate, dependencies, grid navigation, iframes, markdown, mathjax4, multiple instances, PDF, plugins, scroll, and state.

Run tests:

npm test            # Core: QUnit in headless Puppeteer
npm run react:test  # React wrapper: Vitest

9. Integration Points

9.1 React Wrapper (@revealjs/react v0.2.1)

The React wrapper lives in the react/ subdirectory and provides a declarative component API for building presentations in React.

Components

Deck -- The root component that wraps a reveal.js instance.

Slide -- Maps to a <section> element with shorthand props for all data-* attributes.

Stack -- Wraps vertical slides in a parent <section>.

Markdown -- Renders markdown content as slides.

Fragment -- Wraps elements in fragment animations.

Code -- Renders syntax-highlighted code blocks.

Hooks and Context

• useReveal() -- Hook that returns the RevealApi instance from RevealContext. Must be called within a Deck component tree.
• RevealContext -- React context providing the RevealApi instance.

Note

GitHub issue #3883 documents that React Markdown fragment directives are broken with Vite 8. Verify fragment behavior when using the Markdown component with the current build toolchain.

9.2 PostMessage API

When postMessage: true, reveal.js accepts commands from parent/child windows:

// From parent window controlling an embedded presentation
iframe.contentWindow.postMessage(JSON.stringify({
  method: 'slide',
  args: [2, 0]  // Navigate to slide 2
}), '*');

When postMessageEvents: true, all reveal.js events are forwarded as postMessage to the parent window, enabling external monitoring and synchronization.

9.3 Multiplexing and Synchronization

State synchronization between presenter and audience can be built using:

1. getState() / setState() -- serialize and restore complete presentation state
2. postMessageEvents: true -- forward all events to a parent frame or relay server
3. slidechanged event -- includes indexh, indexv for remote navigation commands

9.4 Embedding

Set embedded: true for presentations embedded within larger pages:

• Prevents capturing global keyboard events
• Adjusts sizing behavior to fit within a container rather than the viewport
• Multiple instances can coexist with independent navigation

9.5 Known Issues and Compatibility

Active GitHub issues relevant to administrators and developers:

Caution

Issue #3869 reports that .background CSS selectors in reveal.js themes are not scoped and can leak styles to the host page. When embedding reveal.js in a larger application, use CSS containment or shadow DOM to prevent style conflicts.

9.6 Troubleshooting

Presentation Root Not Found

Error: "Unable to find presentation root (<div class="reveal">)"

Cause: Reveal.initialize() runs before the .reveal div exists in the DOM, or the element is missing entirely.

Solution: Ensure the HTML contains <div class="reveal"><div class="slides">...</div></div> and that initialization runs after DOM ready (e.g., in a DOMContentLoaded handler or at the end of <body>).

Prevention: Always verify DOM structure before calling initialize().

Plugins Not Loading

Error: ready event never fires; presentation appears stuck.

Cause: A plugin's init() method returned a Promise that never resolves or threw an error.

Solution: Check browser console for plugin initialization errors. Test with plugins: [] to confirm the issue is plugin-related. Add each plugin back one at a time to identify the failing one.

Prevention: Always handle errors in async plugin init() methods. Test plugin initialization in isolation.

PDF Export Issues

Error: Blank pages, missing content, or excessively large file size in PDF export.

Cause: Fragment-based pagination (pdfSeparateFragments: true) generates a page per fragment step. Complex backgrounds and media increase file size.

Solution: Set pdfSeparateFragments: false to reduce page count. Use pdfMaxPagesPerSlide to cap pages per slide. Remove or simplify heavy backgrounds before export.

Prevention: Test PDF export early in presentation development. Use ?print-pdf in the URL to preview print layout.

npm Install Failures

Error: Various errors during npm install (see issue #3821).

Cause: Node.js version below the required minimum (20.19.0) or platform-specific dependency issues.

Solution: Verify Node.js version with node --version. Ensure it meets the >= 20.19.0 requirement in package.json engines.

Prevention: Use nvm or fnm to manage Node.js versions and pin to a compatible version.