impress.js Admin & Developer Guide

This guide is for developers extending impress.js, maintainers of the project, and architects who need to understand how the framework is built, how its plugin system works, and how to deploy and self-host presentations. For authoring presentations, see the companion User Guide.

Table of Contents

1. Executive Summary
2. Architecture Overview
3. Repository Structure
4. Core Engine Deep Dive (src/impress.js)
5. The Library Layer (src/lib/)
6. The Plugin System
7. Plugin Reference (by type)
8. The Build Pipeline
9. Configuration Reference
10. Deployment & Hosting
11. Security Analysis
12. Code Quality & Conventions
13. Testing Strategy
14. Writing a Plugin (extension recipe)
15. Potential Improvements & Tech Debt
16. Quick Reference

1. Executive Summary

impress.js is a client-side presentation framework written in dependency-free, ES5-style vanilla JavaScript. It transforms a tree of <div class="step"> elements positioned with data-* attributes into a zoomable, pannable, rotatable 3D presentation, driven entirely by CSS3 transforms/transitions and a small JavaScript engine.

Note

There is no server component, database, runtime API, or deployment infrastructure in impress.js itself. "Deployment" means serving static HTML/JS/CSS files. This guide therefore focuses on the build pipeline, plugin architecture, and extension model rather than operations.

Important

Version inconsistency in the repo. package.json declares "version": "1.1.0", but the source header in src/impress.js says version: 2.0.0, the CDN serves a @2.0.0 tag, and DOCUMENTATION.md references a v1.2.0 default-resolution change. Treat 2.0.0 as the effective released version (matching the latest tag) and the package.json value as stale. Several open issues (#653 "push v1.0.0 to npm", #879 "Publish Library to NPM") reflect the unfinished release/publishing process.

2. Architecture Overview

impress.js is organized as four layers that the build concatenates into one file:

+-----------------------------------------------------------+
|                     js/impress.js                          |
|              (generated build artifact)                    |
|                                                            |
|  +-----------------------------------------------------+   |
|  | Layer 1: CORE  (src/impress.js)                     |   |
|  |  - window.impress() factory -> API per root         |   |
|  |  - init / goto / next / prev / swipe / tear         |   |
|  |  - config + step data parsing from data-* attrs     |   |
|  |  - the canvas/root transform engine                 |   |
|  |  - plugin + library registration hooks              |   |
|  +-----------------------------------------------------+   |
|                          ^                                  |
|  +-----------------------------------------------------+   |
|  | Layer 2: LIBRARIES (src/lib/*.js)                   |   |
|  |  gc.js (garbage collection / teardown)              |   |
|  |  util.js ($/$$/byId/triggerEvent/toNumber...)       |   |
|  |  rotation.js (quaternion math for rel plugin)       |   |
|  |  -> registered via impress.addLibraryFactory()      |   |
|  |  -> exposed to plugins as api.lib.*                 |   |
|  +-----------------------------------------------------+   |
|                          ^                                  |
|  +-----------------------------------------------------+   |
|  | Layer 3: PLUGINS (src/plugins/*/*.js) x22           |   |
|  |  pre-init | pre-stepleave | init (event) plugins    |   |
|  +-----------------------------------------------------+   |
+-----------------------------------------------------------+
            |  reads at runtime
            v
   Author's HTML: <div id="impress"> <div class="step" data-*>
            |
            v
   Browser: CSS3 transforms on root (scale) + canvas (translate/rotate)

The camera model. impress.js never moves the slides. On init(), it wraps all steps inside a canvas div inside the root div. To "go to" a step, it computes the inverse of that step's transform (negated translate/rotate, reciprocal scale) and applies it to the canvas + root, so the target step lands centered and upright. The root element animates scale (zoom); the canvas element animates translate + rotate. They use staggered transition delays so zoom-in starts with movement and delays scaling, while zoom-out scales first — making transitions feel natural.

Two coordinate concerns split across two elements is the single most important architectural fact to internalize before reading goto().

3. Repository Structure

impress.js/
├── index.html              Official demo (also the canonical, commented tutorial)
├── README.md               Project overview, install, browser support
├── DOCUMENTATION.md        Reference API (data-* attrs, CSS classes, JS API)
├── GettingStarted.md       Beginner tutorial
├── npm-readme.md           README variant for npm packaging
├── build.js                Build script (concat + Terser minify + examples index)
├── package.json            Build/test tooling spec (NOT a runtime dependency)
├── karma.conf.js           Karma test runner config
├── qunit_test_runner.html  Browser-based QUnit runner
├── css/
│   ├── impress-common.css  OPTIONAL sample plugin CSS (help/toolbar/progress/...)
│   └── impress-demo.css    Styling for the official demo
├── js/
│   └── impress.js          GENERATED bundle (core + libs + all plugins)
├── src/                    AUTHORED SOURCE (source of truth)
│   ├── impress.js          Core engine
│   ├── lib/
│   │   ├── gc.js           Garbage collection / teardown
│   │   ├── util.js         DOM + numeric helpers
│   │   ├── rotation.js     Quaternion rotation math (used by rel)
│   │   └── README.md
│   └── plugins/            22 default plugins, one dir each (plugin.js + README.md)
├── examples/               Demo presentations (classic-slides, cube, 3D-rotations, ...)
├── extras/                 Git submodule mount point for impress-extras (empty by default)
└── test/                   QUnit/Syn tests for core + per-plugin tests

Warning

js/impress.js is a build artifact, regenerated by build.js (cat src/impress.js src/lib/*.js src/plugins/*/*.js). Never hand-edit it — edit the files under src/ and rebuild. The minified js/impress.min.js is not committed to the repo (it's generated at build time).

Note

Each plugin directory contains its own README.md — these are the authoritative per-feature docs and are the basis for the User Guide's plugin catalog.

4. Core Engine Deep Dive (src/impress.js)

The core is a single IIFE ( function( document, window ) { ... } )( document, window ). Key internals:

Feature detection

On load, the core builds a pfx() vendor-prefix resolver (Modernizr-style) and computes impressSupported:

var impressSupported =
    ( pfx( "perspective" ) !== null ) &&   // CSS 3D transforms
    ( body.classList ) &&                  // ClassList API
    ( body.dataset );                      // DataSet API

If unsupported, it adds impress-not-supported to the body, and impress() returns a dummy API (all no-op functions) so author code calling .init() etc. won't throw.

The impress(rootId) factory

window.impress = function(rootId) returns (and caches) the API object for a given root id ("impress" by default). Each root gets its own closure with its own stepsData, activeStep, currentState, steps, windowScale, and a fresh set of library instances.

Defaults & config

var defaults = {
    width: 1920, height: 1080,
    maxScale: 3, minScale: 0,
    perspective: 1000, transitionDuration: 1000
};

buildConfig() reads the root element's dataset and falls back to these defaults. impress.getConfig() exposes the resolved config (used by util.toNumberAdvanced to compute w/h relative units).

Step initialization

initStep(el, idx) reads each step's data-* attributes into a stepsData record:

step = {
    translate: { x, y, z },                 // via util.toNumberAdvanced (supports w/h units)
    rotate:    { x, y, z, order },          // data-rotate-z falls back to data-rotate
    scale:     toNumber(data.scale, 1),
    transitionDuration: toNumber(data.transitionDuration, config.transitionDuration),
    el
};

Steps without an id are auto-assigned step-N. initAllSteps() runs on every goto(), which is why you can mutate step coordinates at runtime and have them apply on the next transition.

The transform engine (goto)

goto(el, duration, reason, origEvent) is the heart of the engine:

1. Re-reads all steps (initAllSteps()).
2. Resolves the target via getStep() (accepts index, id, or element; negative indices count from the end).
3. Runs execPreStepLeavePlugins(event) — pre-stepleave plugins may redirect (event.detail.next), retime (transitionDuration), or abort (return false).
4. Updates .active classes and the impress-on-{id} body class.
5. Computes the target canvas state as the inverse of the step transform (negated rotate/translate, 1/scale).
6. Determines zoomin direction to choose the transition-delay strategy.
7. Applies CSS to root (perspective + scale) and canvas (rotate + translate) with staggered transitionDelay.
8. Fires impress:stepenter after duration + delay via setTimeout (chosen over transitionend for simplicity across two animated elements).

Navigation helpers

• prev(origEvent) / next(origEvent) walk steps in document order, wrapping around at the ends.
• swipe(pct) is a semi-internal API used by the touch plugin to animate a partial swipe (interpolating between current and adjacent step states); committing the transition is the caller's responsibility. It is intentionally undocumented in DOCUMENTATION.md.

Events

The core triggers four custom events on the root: impress:init, impress:stepenter, impress:stepleave, impress:steprefresh. It also wires up:

• Step state classes (future/present/past) on enter/leave.
• Hash sync: writes #/step-id on enter, listens for hashchange to goto() the hashed step, and starts on the hashed step (or step 0) at init.

The returned API

{ init, goto, next, prev, swipe, tear, lib }

Plus static members: impress.supported, impress.addLibraryFactory, impress.addPreInitPlugin, impress.addPreStepLeavePlugin, impress.getConfig.

5. The Library Layer (src/lib/)

Libraries are registered with impress.addLibraryFactory({ name: factoryFn }) and instantiated per-root inside initLibraries(). They're exposed to plugins as api.lib.{name}. A name collision throws impress.js ERROR: Two libraries both tried to use libname: ....

gc.js — Garbage collection / teardown

The mechanism that makes tear() possible. Plugins register the DOM elements and event listeners they create so they can all be cleanly removed:

gc also records the DOM's "virgin" state at init (recordStartingState) — original step ids, the body's impress-not-supported class, and the viewport <meta> — and restores it on teardown (resetStartingState). This is what lets you tear() → modify → init() again without residue.

Tip

Any plugin that injects DOM or binds events must route them through api.lib.gc so tear() works correctly. This is the most important convention for plugin authors.

util.js — DOM & numeric helpers

rotation.js — Quaternion math

A self-contained quaternion/vector library (dot/cross/triple products, quaternion multiplication, coordinate↔rotation conversion, bestRotation selection). Its public surface is a single translateRelative(relative, prevRotation) function. It exists to support the rel plugin's data-rel-position="relative" feature, which must compose rotations correctly so a slide can be positioned relative to the rotated frame of a previous slide.

6. The Plugin System

impress.js has three distinct plugin types, distinguished by when and how they hook into the core.

Type 1: Init plugins (event-driven)

The simplest and most common. They listen for impress:init on the document, grab the API from event.detail.api, and then bind their own behavior using the public API and api.lib.*. They never touch core internals.

document.addEventListener( "impress:init", function( event ) {
    var api = event.detail.api;
    var gc  = api.lib.gc;
    // ... bind keydown/keyup/click using api.next(), api.prev(), api.goto()
}, false );

Examples: navigation, navigation-ui, progress, help, blackout, fullscreen, impressConsole, mobile, resize, mouse-timeout, toolbar, form, media, touch, autoplay, bookmark.

Type 2: Pre-init plugins (attribute filters)

Registered via impress.addPreInitPlugin(fn, weight). They run synchronously at the very start of init(), before the core reads step attributes. This lets them rewrite data-* attributes that the core will then consume.

impress.addPreInitPlugin( rel );   // weight defaults to 10

• weight (positive integer, default 10) controls ordering — lower runs first. Non-positive weight throws.
• The canonical example is rel, which converts data-rel-* into absolute data-x/data-y/data-z before the core parses them.

Type 3: Pre-stepleave plugins (transition interceptors)

Registered via impress.addPreStepLeavePlugin(fn, weight). They run at the start of every goto(), before the impress:stepleave event. They receive the event object and can:

• Redirect the transition by changing event.detail.next.
• Retime it via event.detail.transitionDuration.
• Abort it entirely by returning false.

Examples: goto (redirect to an out-link), skip (skip a step), stop (cancel forward motion), substep (intercept to reveal a sub-element instead of leaving).

Plugin registration summary

Inter-plugin communication

Plugins coordinate through custom DOM events rather than direct calls. The help plugin, for instance, exposes an impress:help:add event; other plugins dispatch it to register a help line:

util.triggerEvent( document, "impress:help:add",
    { command: "Left & Right", text: "Previous & Next step", row: 1 } );

This keeps plugins decoupled — the navigation plugin doesn't need a reference to the help plugin.

7. Plugin Reference (by type)

Note

rel carries a documented backward-incompatible side effect: with it enabled, a missing data-x/y/z inherits from the previous step instead of defaulting to 0. Its registration line (impress.addPreInitPlugin( rel );) can be commented out to disable the behavior without removing the file.

8. The Build Pipeline

The build is deliberately minimal — concatenation plus minification. build.js (run with node build.js):

1. Concatenates files in a fixed order into js/impress.js:
   • src/impress.js (core) first
   • then src/lib/gc.js, src/lib/util.js, src/lib/rotation.js
   • then all 22 plugins in src/plugins/*/*.js (explicit order list in build.js)
   • prepended with a generated header comment.
2. Minifies with Terser into js/impress.min.js + a source map js/impress.min.js.map (preserving /^!/ license comments). These minified outputs are not committed.
3. Auto-generates examples/index.html — an <ul> linking every subdirectory under examples/ (used for the gh-pages examples listing).

npm install        # installs build + test tooling
npm run build      # node build.js  -> regenerates js/impress.js (+ .min.js)

Important

Plugin load order is defined explicitly in build.js, not by directory glob alphabetization. If you add a plugin, add it to the files.push(...) list in build.js. Pre-init/pre-stepleave ordering at runtime is governed by the weight argument, but file order still affects which code registers first.

The build essentially does cat src/impress.js src/lib/*.js src/plugins/*/*.js > js/impress.js. The only npm packages it relies on are buildify/ls/terser; impress.js at runtime depends on nothing.

npm scripts (package.json)

Dev requirements

• Node >= 7.6
• npm

9. Configuration Reference

impress.js has no configuration file and no environment variables. All configuration is HTML data-* attributes, resolved at runtime.

Note

The single entry in the extracted config_keys data is CHROME_BIN (a process.env read in karma.conf.js) — that is a test-harness variable for pointing Karma at a Chrome binary, not a runtime setting of the library. There are no runtime env vars.

Root configuration (defaults from src/impress.js)

All other data-* attributes are consumed per-step by the core (data-x/y/z, data-rotate*, data-scale, data-rotate-order, per-step data-transition-duration) or by individual plugins (see the User Guide reference and Section 7).

Test-harness configuration

karma.conf.js reads process.env.CHROME_BIN to locate a Chrome/Chromium binary for headless testing. puppeteer is a devDependency that can supply one.

10. Deployment & Hosting

Because a presentation is just static files, "deployment" is serving HTML/CSS/JS.

Option A: Single self-contained directory

Ship your index.html, your CSS, a local js/impress.js, and any media. Open the file directly or serve it from any static host (GitHub Pages, Netlify, S3, nginx, etc.).

my-talk/
├── index.html
├── css/
│   ├── impress-common.css   (optional)
│   └── my-style.css
├── js/
│   └── impress.js
└── images/

Option B: CDN for the framework

Reference https://cdn.jsdelivr.net/gh/impress/impress.js@2.0.0/js/impress.js and host only your own HTML/CSS. Lighter to deploy, but requires network access at present time.

Tip

Pin a specific @version in the CDN URL for reproducibility. The unversioned .../impress.js/js/impress.js always tracks the latest source and can change under you.

Self-hosting the project / examples (gh-pages model)

The project's own demos are published to GitHub Pages (http://impress.github.io/impress.js/). build.js regenerates examples/index.html so the examples listing stays current. To self-host the demos, build and serve the repository root as static files.

Warning

No build step is required to deploy a presentation — only to regenerate js/impress.js from src/. End users serving a pre-built js/impress.js need no Node toolchain at all.

11. Security Analysis

impress.js is a client-side library with no server, no network calls, no authentication, no secrets, and no data persistence. Its attack surface is correspondingly small, but there are real considerations for anyone embedding it in a larger application.

Threat model

Key findings

Caution

Untrusted content = XSS risk. impress.js renders whatever HTML you put in your steps. If any part of a presentation is built from user-supplied or remote content (e.g. a CMS, comments, query parameters), you must sanitize it yourself before injecting it into a step. The framework provides no sanitization layer.

Warning

Plugins use innerHTML. The help plugin assembles its popup with helpDiv.innerHTML = "<table>" + rows.join() + "</table>", where rows come from impress:help:add events. Any plugin that dispatches that event controls markup written to the DOM. In a trusted, author-controlled deck this is fine; if you let third parties register help text or write plugins, treat the help/toolbar text as a markup sink.

Note

The data-goto/data-bookmark key handling and URL hash routing read values from the page/URL and getElementById them. They locate existing elements rather than executing strings, so they are not script-injection vectors, but a malicious hash simply navigates the deck — not a meaningful risk for a presentation.

Tip

pointer-events workaround. impress-common.css sets pointer-events: none on .impress-enabled and re-enables it on #impress (and toolbar/console buttons) to work around a Chrome bug where Z-pushed elements fall behind <body>. This is a usability fix, not a security boundary, but be aware it makes everything outside #impress unclickable when applied.

Hardening checklist (for embedding impress.js in an app)

• [ ] Sanitize any non-author content before placing it in a step (use a vetted sanitizer like DOMPurify).
• [ ] Don't expose the impress:help:add event surface to untrusted code.
• [ ] Serve over HTTPS and pin the CDN version if loading remotely.
• [ ] Apply a Content-Security-Policy on the hosting page; impress.js needs no eval or remote scripts of its own (it does not use eval).
• [ ] Audit any extra add-ons you include — they are third-party code outside the impress.js codebase.

12. Code Quality & Conventions

Note

The codebase predates ES modules and bundler ecosystems and stays intentionally framework-free. This is a deliberate design value ("showcase awesome CSS3 features... do not use jQuery or any other JavaScript libraries"), not technical debt.

Extraction caveat for tooling

Static analysis tools that look for function name( / class X declarations will find almost nothing here — the entire API is built from function expressions assigned to vars and returned in object literals, inside IIFEs. The authoritative API surface is DOCUMENTATION.md plus the returned object in src/impress.js (the { init, goto, next, prev, swipe, tear, lib } literal and the impress.* static assignments).

13. Testing Strategy

Tip

The maintainers note that running firefox qunit_test_runner.html is often more informative than karma (npm run test) — they run the same tests, but the browser runner gives clearer output. Use Karma for CI, the browser runner for debugging.

Note

Test coverage is acknowledged as incomplete ("Yes, more tests are much welcome"). The rel plugin is the best-covered plugin; most other plugins have thin or no tests. This is the largest quality gap (see Improvements).

14. Writing a Plugin (extension recipe)

A. Init plugin (most common)

Use this when your plugin reacts to navigation or adds UI/behavior.

/* global document */
( function( document ) {
    "use strict";

    document.addEventListener( "impress:init", function( event ) {
        var api  = event.detail.api;   // the impress API for this root
        var gc   = api.lib.gc;         // ALWAYS route DOM/listeners through gc
        var util = api.lib.util;

        // Bind behavior using the public API
        gc.addEventListener( document, "keyup", function( e ) {
            if ( e.keyCode === /* your key */ 0 ) {
                api.next();
            }
        }, false );

        // Optionally register a help line
        util.triggerEvent( document, "impress:help:add",
            { command: "X", text: "What X does", row: 5 } );
    }, false );

} )( document );

Important

Route every element you add and every listener you bind through api.lib.gc (gc.addEventListener, gc.appendChild, gc.pushElement, gc.pushCallback). Otherwise impress().tear() will leave your plugin's DOM/listeners behind.

B. Pre-init plugin (rewrite step attributes before init)

( function( document, window ) {
    "use strict";
    var impress = window.impress;

    var myPreInit = function( root ) {
        // Read your custom data-* attrs and write data-x/y/z etc.
    };

    impress.addPreInitPlugin( myPreInit, 10 ); // weight: lower runs first
} )( document, window );

C. Pre-stepleave plugin (redirect/abort transitions)

( function( document, window ) {
    "use strict";
    var impress = window.impress;

    var myPreStepLeave = function( event ) {
        // event.detail.next, .reason, .transitionDuration are mutable
        // return false to ABORT the transition
        if ( /* condition */ false ) {
            return false;
        }
    };

    impress.addPreStepLeavePlugin( myPreStepLeave, 10 );
} )( document, window );

D. Add it to the build

Append your file to the files.push(...) list in build.js (mind the order), then npm run build. Add a README.md in your plugin directory and a test under test/plugins/yourplugin/.

Recipe checklist

• [ ] IIFE + "use strict"
• [ ] Choose the correct plugin type (init / pre-init / pre-stepleave)
• [ ] Use the public API + api.lib.* only — don't reach into core internals
• [ ] Route all DOM/listeners through gc
• [ ] Register help text if you bind a key
• [ ] Add to build.js, write a README.md, add tests
• [ ] Verify tear() cleans up your plugin

15. Potential Improvements & Tech Debt

Drawn from the source, the project's own READMEs, and the open GitHub issues.

Release & packaging

• Version inconsistency between package.json (1.1.0) and the source/CDN (2.0.0). Reconcile and bump package.json.
• Not published to npm (issues #879, #653). A real npm package would let users npm install and enable bundler workflows. (#700 also asks for extra add-ons as npm dependencies.)
• Consider a proper release artifact that includes the minified js/impress.min.js (currently uncommitted).

Architecture & features

• Multiple-root support is half-hearted — the code supports several #impress roots per page but warns it's not really intended; issue #664 proposes removing it. Decide: support it properly or drop it.
• Hash-based routing clutters browser history (#644) — each step pushes a history entry; history.replaceState would avoid the back-button pile-up.
• Step-independent zoom/pan (#649) is a requested capability the current camera model doesn't expose.
• Resize transition hardcoded to 500 ms (#682).
• Scaling quality on lower-than-config resolutions produces blurriness (#609) — a known CSS scale artifact.

Mobile

• Positioning is off on some mobile devices (#844). The mobile plugin notes it doesn't account for non-linear (skip/goto) transitions.

Code & docs

• Form plugin is incomplete — Tab navigation between form fields is unsupported because the navigation plugin must own the Tab key (flagged in the plugin's own README, "REQUIRES FURTHER DEVELOPMENT").
• No JSDoc API documentation (#662) — the API is documented in prose (DOCUMENTATION.md) but not machine-readable.
• Documentation gaps: add gc usage docs to src/plugins/README.md (#677); a media-plugin usage example (#689); a bug in GettingStarted was reported (#860, closed).
• Thin test coverage outside the rel plugin (acknowledged in README). Each plugin should get a test/plugins/<name>/ suite.
• Dual lint toolchains (jshint+jscs legacy alongside eslint) should converge on ESLint and the legacy configs/scripts be retired.
• A "Major Refactor" is an open umbrella issue (#863).
• No dedicated project webpage (#645).

Maintainability notes

• The build's explicit plugin list in build.js must be kept in sync manually when plugins are added/removed.
• extras/ depends on a git submodule (impress-extras); a non-recursive clone silently omits it.

16. Quick Reference

Build & test

npm install
npm run build      # node build.js -> js/impress.js (+ .min.js, .map)
npm run test       # karma headless
npm run new-lint   # eslint src test
npm run all        # build + test + lint
firefox qunit_test_runner.html   # browser test runner (more verbose)

Core API (returned by impress(rootId))

Static members on impress

Events (on the root element)

impress:init · impress:stepenter · impress:stepleave · impress:steprefresh

Plugin coordination events

impress:help:add (register a help-popup line)

Build order (from build.js)

src/impress.js
src/lib/{gc,util,rotation}.js
src/plugins/{autoplay,blackout,extras,form,fullscreen,goto,bookmark,help,
             impressConsole,media,mobile,mouse-timeout,navigation,navigation-ui,
             progress,rel,resize,skip,stop,substep,touch,toolbar}/*.js

Key files