` positioned with `data-*` attributes (`data-x`, `data-y`, `data-z`, `data-rotate`, `data-scale`). One line of JavaScript — `impress().init()` — starts the show. > [!NOTE] > impress.js is a **framework you build presentations with**, not an application you run. There is nothing to "launch." You write an HTML file, include the `impress.js` script, and open it in a browser. --- ## Table of Contents 1. [Quick Start](#1-quick-start) 2. [Requirements](#2-requirements) 3. [Installation](#3-installation) 4. [Building Your First Presentation](#4-building-your-first-presentation) 5. [Positioning Slides (the data-* attributes)](#5-positioning-slides-the-data--attributes) 6. [Presentation Settings (the root element)](#6-presentation-settings-the-root-element) 7. [Navigating a Presentation (keyboard, mouse, touch)](#7-navigating-a-presentation-keyboard-mouse-touch) 8. [Styling with impress.js State Classes](#8-styling-with-impressjs-state-classes) 9. [Plugin Catalog](#9-plugin-catalog) 10. [Extra Add-ons (Markdown, Mermaid, syntax highlighting)](#10-extra-add-ons-markdown-mermaid-syntax-highlighting) 11. [The JavaScript API](#11-the-javascript-api) 12. [Common Tasks (recipes)](#12-common-tasks-recipes) 13. [How It Works (concepts)](#13-how-it-works-concepts) 14. [Troubleshooting](#14-troubleshooting) 15. [FAQ](#15-faq) 16. [Reference](#16-reference) --- ## 1. Quick Start Create a file called `index.html`, paste this in, and open it in Chrome or Firefox. Use the **arrow keys** or **spacebar** to move between slides. ```html My first presentation

Hello, impress.js

This slide is rotated 90°

And this one is zoomed in

``` ```text A full-screen presentation opens on the first slide. Press the Right arrow or Space to fly to the rotated slide, then again to zoom into the third. ``` > [!TIP] > That's the entire model: a `#impress` container, one `

` per slide positioned with `data-*` attributes, and `impress().init()`. Everything else in this guide builds on these three ideas. --- ## 2. Requirements impress.js runs in the **viewer's browser** — there is no server, build step, or account required to *present*. The only requirement is a reasonably modern browser. | Feature used | Why | Browser support | |---|---|---| | CSS 3D Transforms | The core 3D positioning/camera | Modern Chrome, Firefox, Safari, Edge | | CSS Transitions | The animated movement between steps | Modern Chrome, Firefox, Safari, Edge | | `dataset` (DataSet API) | Reads `data-*` attributes from your HTML | Modern browsers | | `classList` (ClassList API) | Adds/removes state classes | Modern browsers | > [!IMPORTANT] > The typical and recommended use case is presenting **from your own laptop** with a browser version you have tested. If you embed an impress.js presentation in a public web page, some visitors on older browsers may see only the fallback message (see [Section 8](#8-styling-with-impressjs-state-classes)). > [!NOTE] > impress.js deliberately uses **no jQuery and no other JavaScript libraries**, and does not polyfill older browsers. Recent Firefox and Chrome are known to work well; recent versions of other major browsers generally work too. --- ## 3. Installation There are two ways to get impress.js into your presentation. Pick based on whether you'll have a reliable internet connection when you present. > [!CAUTION] > If you are **not certain you'll have WiFi** during your talk, download a local copy (Method B). A CDN-only setup will fail to load with no network. === "From a CDN (no download)" Include one ` ``` Pinned version links: | Version | jsDelivr URL | |---|---| | v2.0.0 | `https://cdn.jsdelivr.net/gh/impress/impress.js@2.0.0/js/impress.js` | | v1.1.0 | `https://cdn.jsdelivr.net/gh/impress/impress.js@1.1.0/js/impress.js` | | latest source | `https://cdn.jsdelivr.net/gh/impress/impress.js/js/impress.js` | === "Download a local copy" 1. Go to the [GitHub Releases page](https://github.com/impress/impress.js/releases) and download the source as a `.zip` or `.tar`. 2. Unzip it. 3. Copy the `js/` folder into your project directory. 4. (Optional) Copy the `css/` folder too, if you want the sample plugin styling in `impress-common.css`. ```html ``` === "Belt-and-suspenders (local + CDN fallback)" Use a local file but fall back to the CDN automatically if it's missing: ```html ``` ### About `impress-common.css` impress.js **does not require any CSS file** — it generates the positioning CSS it needs dynamically. However, the bundled `css/impress-common.css` provides sample styling that several plugins need to look right (the help popup, toolbar, progress bar, speaker-notes hiding, and the mouse-timeout cursor hiding). Link it if you use those plugins: ```html ``` > [!NOTE] > impress.js is **not currently published to npm**. The `package.json` in the repo exists mainly to run the build and test tooling. Install it by downloading a release or linking the CDN, not via `npm install`. > [!WARNING] > The file you link in the browser is `js/impress.js` — a generated bundle that concatenates the core and **all default plugins**. The files under `src/` are the authored source and are not meant to be linked individually in a presentation. --- ## 4. Building Your First Presentation A presentation has three required pieces. ### 4.1 The fallback message (recommended) Put a class of `impress-not-supported` on the `` and include a fallback block. If the browser can't run impress.js, the visitor sees this message instead of a broken page. impress.js removes the class automatically when it detects support. ```html

Your browser doesn't support the features required by impress.js, so you are presented with a simplified version of this presentation.

For the best experience please use the latest Chrome, Safari or Firefox browser.

... ``` ### 4.2 The root element All presentation content lives inside a single root element, by default the one with `id="impress"`. Anything outside it is **not** animated by impress.js. ```html

``` ### 4.3 The steps Each slide is a `

`. Give it an `id` if you want a friendly URL hash and easy navigation targets (otherwise impress.js auto-assigns `step-1`, `step-2`, …). ```html

Welcome

``` > [!WARNING] > Do **not** apply your own CSS `transform`, `position`, `width`, or `height` directly to a `.step` element — impress.js controls those. If you need custom styling or layout, put a child `

` inside the step and style that instead. ```html

Powerful, yet still simple

``` > [!TIP] > Because every step is wrapped in a zero-size box, you **cannot** use percentage widths/heights (`width: 100%`) for step content. Use pixel values that correspond to your target `data-width`/`data-height` (see [Section 6](#6-presentation-settings-the-root-element)). --- ## 5. Positioning Slides (the data-* attributes) You place each step on the infinite canvas by setting `data-*` attributes. The values position the **center** of the step. All values are strings, so quote your numbers. Negative numbers are allowed everywhere. | Attribute | Default | What it does | |---|---|---| | `data-x` | `0` | X position (left ↔ right), in pixels | | `data-y` | `0` | Y position (top ↔ bottom), in pixels | | `data-z` | `0` | Z position (depth toward/away from camera), in pixels | | `data-scale` | `1` | Size multiplier relative to other steps (e.g. `4` = 4× larger) | | `data-rotate` | `0` | Clockwise rotation in degrees (alias for `data-rotate-z`) | | `data-rotate-x` | `0` | Rotation around the X axis, in degrees | | `data-rotate-y` | `0` | Rotation around the Y axis, in degrees | | `data-rotate-z` | `0` | Rotation around the Z axis, in degrees | | `data-rotate-order` | `xyz` | Order the X/Y/Z rotations are applied | | `data-transition-duration` | inherits root | Per-step transition time in ms (overrides the global setting) | ### Examples A step moved left and up: ```html

Aren't you just bored with slides-based presentations?

``` A zoomed-in title: ```html

impress.js

``` A step pushed deep into the background on the Z axis: ```html

and tiny ideas

``` Full 3D rotation around multiple axes: ```html

have you noticed it's in 3D?

``` > [!TIP] > `data-rotate` and `data-rotate-z` are exact aliases — both rotate around the Z axis (the one facing the viewer). > [!NOTE] > `data-rotate-order` matters because each rotation is applied relative to the element's *current* orientation. The default `xyz` works for almost everything; change it only for advanced poses that the default order can't reach. See the bundled `examples/3D-rotations/` demo. ### Relative positioning (the `rel` plugin) Typing absolute coordinates for dozens of slides gets tedious. The built-in **rel** plugin lets you position a step *relative to the previous step*, which means inserting or moving slides rarely forces you to re-do coordinates. ```html

...

``` You can express relative values as multiples of screen width/height with `w`/`h` units: ```html

...

``` See the [rel plugin](#rel--relative-positioning) entry for the full attribute list and an important compatibility note. --- ## 6. Presentation Settings (the root element) Global settings go as `data-*` attributes on the `#impress` root element. They define your **target screen size** — author your CSS as if the screen is exactly this size, and impress.js will scale the whole presentation up or down to fit whatever screen it's shown on. | Attribute | Default | Explanation | |---|---|---| | `data-width` | `1920` | Width of the target screen, in px. Content scales automatically on other sizes. | | `data-height` | `1080` | Height of the target screen, in px. | | `data-max-scale` | `3` | Maximum scale-up factor on larger screens. | | `data-min-scale` | `0` | Minimum scale-down factor on smaller screens. | | `data-perspective` | `1000` | 3D perspective in px. Set to `0` to disable 3D effects. | | `data-transition-duration` | `1000` | Default transition time between steps, in ms (1 s). | ```html

...

``` > [!IMPORTANT] > The default target resolution is **HD (1920×1080)**. If your presentation was authored for the older 1024×768 default, set it explicitly or your layout will look off: > ```html >

> ``` > [!NOTE] > A `data-max-scale` of `1` will *not* enlarge content on screens bigger than your target size — it will only ever shrink. Use a value above `1` (the default is `3`) if you want content to grow on big displays. --- ## 7. Navigating a Presentation (keyboard, mouse, touch) These controls come from the built-in **navigation**, **help**, **blackout**, **fullscreen**, and **impressConsole** plugins, which are all included in `js/impress.js` by default. ### Keyboard | Key | Action | |---|---| | → Right / ↓ Down / Space / Tab / Page Down | Next step | | ← Left / ↑ Up / Page Up / Shift+Tab | Previous step | | H or ? | Toggle the on-screen help popup | | B or . | Blackout — blank/unblank the screen | | F5 | Enter fullscreen (plugin) | | Esc | Exit fullscreen | | P | Open the speaker console (impressConsole) | > [!NOTE] > Tab moves to the **next** step on purpose. impress.js needs to control the Tab key because the browser's default Tab behavior (focusing links/buttons) can scroll the viewport and break the careful 3D positioning. Shift+Tab goes back. > [!TIP] > Modifier combinations like Alt+Tab, Ctrl+…, and Cmd+… are ignored, so switching windows won't accidentally advance your slides. ### Mouse - **Click any non-active step** to fly to it. - **Click a link** whose `href` is `#some-step-id` to navigate to that step. ### Touch The built-in **touch** plugin lets you **swipe** left/right to move between steps on touch devices. Transitions may look slightly different from the keyboard experience. ### The help popup To show the help overlay (and let viewers press H for it), add an empty div anywhere in your page: ```html

``` The popup appears for 7 seconds when the presentation loads, and toggles on H/?. Plugins automatically add their own keys to it (for example, the navigation plugin adds the "Left & Right → Previous & Next step" line). > [!TIP] > Style the help popup yourself, or link `impress-common.css` which includes a ready-made style for `#impress-help`. --- ## 8. Styling with impress.js State Classes impress.js adds CSS classes to your elements as the presentation runs. You hook into these classes to style slides and trigger per-slide animations. ### Step state classes Every step is always in exactly one of three states: | Class | Applied to | Meaning | |---|---|---| | `.future` | Steps not visited yet | Style or hide upcoming slides | | `.present` | The step at the center of the camera right now | Trigger in-slide animations | | `.past` | Steps already visited | Style or hide previous slides | | `.active` | The currently visible step (same as present, available for convenience) | Highlight the current slide | ```css /* Fade non-active steps */ .step { opacity: 0.3; transition: opacity 1s; } .step.active { opacity: 1; } /* Animate something only while its slide is centered */ .present .rotating { transform: rotate(-10deg); transition-delay: 0.25s; } ``` ### The `impress-on-*` body class When a step becomes active, impress.js adds a class to the `` named after the step's id, e.g. `impress-on-overview`. This lets you style globally based on which slide is showing (something you can't do by matching upward from the step to the body): ```css .impress-on-overview .step { opacity: 1; cursor: pointer; } .impress-on-step-1 { background: LightBlue; } ``` ### The `impress-not-supported` / `impress-supported` classes If the browser lacks required features, impress.js adds `impress-not-supported` to the ``; otherwise it adds `impress-supported`. Author your fallback styles against `.impress-not-supported`: ```css .impress-not-supported .step { display: inline-block; /* show steps as a simple stacked list */ } ``` > [!TIP] > Add `class="impress-not-supported"` to the `` yourself in the HTML. That way visitors **with JavaScript disabled** also get the fallback styling — impress.js will remove the class at runtime when it confirms support. --- ## 9. Plugin Catalog Almost every feature beyond positioning is a **plugin**. All of the plugins below are *default plugins* — they are already bundled in `js/impress.js`, so you don't load them separately. Most do nothing until you opt in, usually by adding an HTML attribute, a specific `

`, or a CSS class. | Plugin | How you enable it | What it does | |---|---|---| | [navigation](#navigation) | automatic | Keyboard + mouse navigation between steps | | [navigation-ui](#navigation-ui) | toolbar present | Back/Forward buttons + a slide-picker dropdown | | [touch](#touch) | automatic | Swipe gestures on touch devices | | [rel](#rel--relative-positioning) | `data-rel-*` attributes | Position steps relative to other steps | | [goto](#goto) | `data-goto*` attributes | Non-linear jumps (out-links) | | [bookmark](#bookmark) | `data-bookmark-key-list` | Non-linear jumps via global hotkeys (in-links) | | [skip](#skip) | `class="skip"` | Skip a step during normal next/prev | | [stop](#stop) | `class="stop"` | Stop next() from wrapping past this step | | [substep](#substep) | `class="substep"` | Reveal bullet points one at a time | | [autoplay](#autoplay) | `data-autoplay` | Auto-advance after a timeout | | [progress](#progress) | `.impress-progressbar` / `.impress-progress` divs | Progress bar + slide counter | | [help](#help) | `#impress-help` div | On-screen keyboard help popup | | [blackout](#blackout) | automatic (B/.) | Blank the screen | | [fullscreen](#fullscreen) | automatic (F5) | Enter fullscreen | | [impressConsole](#impressconsole) | automatic (P) | Speaker console with notes + preview | | [mobile](#mobile) | CSS you provide | Hide far-away slides to save resources on phones | | [resize](#resize) | automatic | Re-fit the presentation when the window resizes | | [mouse-timeout](#mouse-timeout) | CSS you provide | Add a body class after 3 s of mouse inactivity | | [toolbar](#toolbar) | `#impress-toolbar` div | A shared GUI toolbar other plugins add widgets to | | [form](#form) | automatic | Make form fields usable inside slides | | [media](#media) | `data-media-*` attributes | Auto play/pause/stop audio & video per step | | [extras](#extras) | extra `