Guide 2 of 2

Add Deck Remote to an HTML page

Already have an HTML page? Add the remote with one line and start a session from your phone. Then choose the controls that help you tell your story, and wire them up with an AI chat or by hand. Starting from nothing? Begin with Design an HTML page from scratch.

Step 1Add the script

Paste this line into your HTML file, just before </body>:

<script async src="https://uxd.zennia.sg/v1/deck-remote.js" data-adapter="auto"></script>

That's all a plain deck needs. async means your page loads and works normally even if the server can't be reached. The page can be hosted anywhere, or opened straight from your laptop (file://).

What data-adapter="auto" does

It checks how your page is built and picks the best way to drive it:

Your pageWhat the phone gets
Slides in the recommended structure: .slide sections inside #deck, plus a global show(n)Full control: slide numbers and titles, Jump to slide, and a Present button (P).
A reveal.js deckFull control through reveal's own API, including fragments.
Any other HTMLNext / Prev press the arrow keys on the page. Scroll up / down move the page. The phone shows the page title instead of slide numbers, and Jump to slide isn't available.

Structure that works best, in the design guide, shows how to build each kind of page so the remote gets the most out of it.

Optional attributes on the tag

AttributeUse it when
data-next-key="PageDown"
data-prev-key="PageUp"
Your page moves on keys other than the arrows.
data-scroll="on" / "off"You want to force the phone's Scroll up / down buttons on or off.
data-present-key="p"
data-present-class="presenting"
Your page has its own present mode: the key that toggles it, and the class it sets on <body>. The phone then shows a Present button instead of Full screen.
data-adapter="reveal", "slides" or "keys"You'd rather name the adapter than let auto detect it.
data-id="my-talk"Two copies of the same file should share a session. By default each file path is its own deck.

Presenting a PowerPoint? The PowerPoint converter turns it into an HTML deck with the remote already built in, with your speaker notes on your phone.

A page that wasn't built for the remote

The one-line tag drives any page, but it does the most on pages built to the recommended structure. To bring an existing page up to it without changing how it looks, give an AI chat the brief and this prompt:

1aMake an existing HTML file remote-ready

You already have an HTML page, made by an AI or by hand, and you want the remote to drive it properly.

Here is an HTML file I already have: [paste or attach]

Using the Deck Remote brief, change it as little as possible so the remote can drive it:
- wrap its slides or sections in #deck and .slide if they aren't already, and add show(n) and is-live
- listen for keys on document, and leave Q and ? free
- add the remote's script tag at the end

Don't change the look or the content. List every change you made, then return the complete file.

Step 2Start a session

Practise first on the demo deck: open it on your laptop, press Q and pair your phone.

  1. Open your page on the laptop (Chrome works best) and press Q. The page shows a QR code, "Scan to unlock this deck", with a room code beside it.
    On an iPad or any screen with no keyboard, tap the bottom middle of the screen, tap the bar that appears there, and choose Presenter remote (QR).
  2. Scan it with your phone. The phone shows the room code first. If it doesn't match the code on the screen in front of you, stop: another page may be trying to borrow the team password. Below the code, in small grey text, is what the page says about itself, for example “This page says it is from” your deck's web address, or “a file on a computer”. The page could be lying, so the code is what to check. Then type the team password on the phone. The laptop never asks for it, because it's on the projector. You get three tries, and the code expires after a minute.
  3. Your phone is now the remote. The QR code disappears from the screen.

Ask a teammate for the password. Don't write it into any HTML file, slide or shared document. Your laptop remembers it for 3 hours, so pressing Q again in that window goes straight to pairing: scan the QR, and your phone shows a two-digit number. The screen asks whether that phone may be the remote. Check the number matches, then press Enter on the laptop (Esc refuses it). Anyone in the room can scan a projected QR, but only the laptop can let a phone in. The phone never keeps the password, so any phone can unlock any session. It does remember that it unlocked before, for 90 days: if strangers have typed so many wrong passwords that unlocking is paused, a phone that has unlocked before still gets in.

A deck opened as a file (from Downloads, say) remembers the session and the 3 hours only while its tab is open, because every file on your laptop could read what it saved otherwise. Close the tab and the next Q asks your phone again.

To end a session, tap the small red End at the top right of the phone. The phone disconnects and the session is deleted. A session also ends by itself 60 minutes after the page is closed.

Already on the phone, with no extra code

  • Next / Previous, and Jump to slide
  • Blank screen (the remote draws its own blackout)
  • Scroll up / down on pages that scroll; hold a button to move in small steps
  • A clock counting up from when you go full screen or into present mode
  • Present or Full screen

If you want one of these, you already have it. Don't build your own.

Step 3Choose your controls

The page tells the story. The remote helps you re-tell it, live and in the order the room needs. A good control replaces a walk back to the laptop, a "can you see this bit?", or something you'd otherwise have to remember. Start by thinking about how you'll be telling it:

When you're…What matters mostReach for
Presenting to a roomPacing, attention, the moment of revealReveals, a spotlight, a timer, speaker notes
Talking it through with a small group or on a callFollowing the conversation wherever it goesGo to section, level of detail, scenarios, switching views
Sharing it for people to read aloneThat it makes sense without youA document or poster view with nothing hidden. The remote is optional.

Then match moments in your story to controls:

In the story, you want to…On your phonekind
Hold the room before you beginBlank screen, or a "Starting in" countdownbuilt in · timer
Land a reveal or a punchlineShow answertoggle · button
Build a complex picture step by stepNext layer · Show everythingbutton · choice
Point at one thingSpotlight while held · Dim the restmomentary · toggle
Compare options or scenariosScenario A / B / C · Before / Afterchoice · toggle
Match the detail to the roomDetail: Summary / Full · Text sizechoice · number
Change how it's readView: Slides / Document / Poster / Timelinechoice
Follow a question elsewhereGo to section · Back to overviewchoice · button
Keep time on an activityExercise timer, large on screentimer
Remember what to saySpeaker notes for this slide, on your phone onlyreadout
Know where you areSection 3 of 5 · Next: Pricingreadout
Bring the audience inA question on screen · Pick a random cardtext · button
Recover when a live demo goes wrongReset demo (asks first)button + confirm

Fewer is better: about 5 to 12 controls, well named and grouped. Don't ask for anything the remote already has built in, like Next / Previous, Jump, Blank screen, Scroll, the clock or Present.

3aControls interview

The best way to find the controls you'll actually use. The AI walks through your story with you.

Here is my HTML file: [paste or attach]
I'll be [presenting it to about [n] people in a room / talking it through on a call / walking a small group through it].

Using the Deck Remote brief, help me decide which phone controls I need. Interview me first, one question at a time:
- Go through the story with me section by section. For each section, ask what I want to happen on screen while I'm talking: reveal something, compare, point at something, change the level of detail, involve the audience, or keep time.
- Ask what I'd otherwise have to walk back to the laptop for.
- Ask what could go wrong live, and what I'd need to recover.
- Ask what I'd like to see on my phone that the audience shouldn't.

Then propose the controls as a table with these columns: moment in the story · what happens on screen · control kind · label · keyboard key · group.
Keep it to about 12 controls or fewer. Mark anything the remote already has built in, so we don't rebuild it. Don't change the file until I agree.

3bQuick suggestions

You're short on time and want a starting list.

Read my HTML file [paste or attach]. Using the Deck Remote brief, suggest phone controls that would help me tell this story live.

Group the suggestions by moment: opening, reveals, comparisons, attention, pacing, audience, recovery. Give each one a kind, a label and a keyboard key. Suggest at most 10, most useful first, and explain each in one line. Don't change the file yet.

These prompts need the brief

The AI doesn't know about Deck Remote. The brief is one page of rules covering how to structure the page, which keys to leave free, and every control the phone can draw. Without it you'll get a page the remote can only half drive.

  • Paste it at the top of your first message, then paste a prompt below it.
  • Or save it once where the AI keeps standing instructions, such as a Project in Claude or ChatGPT, or a Gem in Gemini. Every chat there then knows the rules, and you only paste the prompts.

Download it (.md)

Show the brief
# Deck Remote brief

I'm making an HTML page that I'll present from a laptop and control from my phone with Deck Remote (https://uxd.zennia.sg). Follow these rules whenever you write or change the HTML, so the remote can drive it.

## The file
- One self-contained .html file: HTML, CSS and JavaScript all inline. No build step, no frameworks, no npm. Google Fonts are fine; images are inline SVG or data URIs.
- It must work when opened straight from disk (file://) in Chrome: no fetch() of local files.
- A meaningful <title>. The phone shows it.
- A solid background colour on <body>, and on each slide if slides differ. The phone tints itself to match.
- Always return the complete file, never "rest unchanged".

## Structure
- Every slide, section, poster block, timeline event or step is a <section class="slide"> directly inside <div id="deck">. Nothing else goes directly in #deck.
- Each .slide starts with a heading (h1 to h3), or has an aria-label. That is its title in the phone's "Jump to slide" list.
- Exactly one .slide has the class is-live: the one showing, or, in a scrolling layout, the one in view.
- A global function show(n), 0-based, moves to slide n: it puts is-live on slide n only. In a one-at-a-time layout it shows that slide. In a scrolling layout it scrolls that slide into view. In a scrolling layout, keep is-live in step as the reader scrolls (IntersectionObserver).
- Never put the classes reading or posters on <body>. They pause the remote.

## Keys
- Listen for keydown on document, not on an element. Read e.key. Never check e.isTrusted: the remote's key presses are simulated.
- ArrowRight, PageDown and Space go to the next slide. ArrowLeft and PageUp go back. Home and End go to the first and last.
- P toggles the class presenting on <body>. In presenting mode, hide on-screen chrome (nav buttons, counters, view switchers).
- Ignore keys while focus is in an input, textarea, select or contenteditable, and when Ctrl, Cmd or Alt is held.
- Leave Q and ? free. The remote uses them.

## Several views (only if I ask for them)
- Keep the content once, as the #deck .slide sections, and restyle it per view with CSS keyed on <html data-view="slides|doc|poster|timeline">.
- A global function setView(name) switches views. show(n) must work in every view.

## The remote
The last thing before </body>:

<script async src="https://uxd.zennia.sg/v1/deck-remote.js" data-adapter="auto"></script>

Add data-scroll="on" to that tag if the page scrolls (a document, poster or scrolling story), so the phone gets Scroll up / down.

When I ask for phone controls, replace that tag with this form:

<script async src="https://uxd.zennia.sg/v1/deck-remote.js"></script>
<script>
  function startRemote() {
    DeckRemote.init({
      adapter: 'auto',
      scroll: true,            // only if the page scrolls
      actions: {
        notes: { kind: 'readout', label: 'Notes', value: () => document.querySelector('#deck .slide.is-live')?.dataset.notes || '' },
        answer: { kind: 'toggle', label: 'Show answer', key: 'v', icon: 'eye', onChange: (on) => showAnswer(on) },
      },
    });
  }
  window.DeckRemote ? startRemote() : addEventListener('deckremote:ready', startRemote, { once: true });
</script>

Each entry in actions is one control on the phone. The key is its id: short, stable, never renamed.

| kind | the page supplies | good for |
|---|---|---|
| button | run() | one-off actions: reveal, jump, reset |
| momentary | onPress(), onRelease() | acts only while held: spotlight, peek |
| toggle | onChange(on), optional value | on/off: answer, theme, overlay |
| choice | options (strings, or {value, label, color}), value, onChange(value) | a mode, a scenario, a view, a section |
| number | min, max, step, unit, value, onChange(n) | text size, zoom, speed |
| text | placeholder, maxLength (200 at most), onChange(text) | a message or question on screen |
| timer | seconds, display: 'large', resetKey | one countdown per page |
| readout | value: () => string | shown on the phone only, e.g. speaker notes |

Every control also takes: label (about 20 characters, 40 at most; name the thing, not its state), key ('d' or 'shift+d'), group (a folding section on the phone), confirm: true (asks first), icon (x, one, eye, star, shuffle, note, moon, blank, timer, play, reset, jump, present). A choice can take compact: true.

Rules for controls:
- At most 30 controls, 20 options per choice, one timer.
- Every control calls a named function in the page. Write the function if it doesn't exist.
- A readout refreshes when the slide or a control changes, not on a clock.
- Nothing private in a text or readout.

The remote already provides these, so never build them: Next/Previous, Jump to slide, Blank screen, Scroll up/down, a count-up clock, Present / Full screen, and timer +/- 30 s with preset lengths.

## Speaker notes
Put notes for a slide in a data-notes attribute on its section (200 characters at most), never on screen. The readout above shows them on the phone.

Step 4Add the controls

There are two ways to do it: ask an AI chat to add the controls you chose, or write the few lines yourself, as shown here.

Custom controls let the phone change things on your page, like switching a theme, revealing an answer, showing a message or starting a countdown. You describe each control as data, and the phone works out how to draw it.

To add controls, replace the one-line tag from step 1 with the tag without data-adapter, followed by a short script:

<script async src="https://uxd.zennia.sg/v1/deck-remote.js"></script>
<script>
  function startRemote() {
    DeckRemote.init({
      adapter: 'auto',   // same detection as data-adapter="auto"
      actions: {
        // one entry per control on the phone
        dark: {
          kind: 'toggle',
          label: 'Dark mode',
          key: 'd',                 // optional keyboard shortcut on the laptop
          icon: 'moon',
          onChange: (on) => document.body.classList.toggle('dark', on),
        },
        answer: {
          kind: 'button',
          label: 'Reveal answer',
          icon: 'eye',
          run: () => document.getElementById('answer').hidden = false,
        },
      },
    });
  }
  // The script loads async, so wait for it if it isn't here yet.
  window.DeckRemote ? startRemote() : addEventListener('deckremote:ready', startRemote, { once: true });
</script>

How it fits together

  • Each key in actions is the control's id, e.g. dark or answer. Keep ids short and don't rename them later, because they key the value the page restores after a reload.
  • The behaviour lives in your page. A control calls a function, like run or onChange, and that function does the work: toggles a class, sets a CSS variable, calls a function your page already has.
  • One DeckRemote.init per page. Put every control in the same actions object.
  • Keep the last line. The script tag is async, so DeckRemote may not exist yet when your script runs. The last line waits for it.
  • Controls work from the keyboard too. Give a control a key and it fires on the laptop as well, even with no phone paired.
  • Values survive a reload. Toggles, choices, numbers and the timer come back when the page reloads mid-session.

Or ask an AI to add them

With the brief in the chat, paste the table of controls you agreed in step 3:

4aAdd the agreed controls

After 3a or 3b, once you've agreed the list.

Add these controls to my HTML file, using DeckRemote.init as described in the Deck Remote brief:
[paste the agreed table]

- Replace the one-line remote tag with the init form, keeping adapter: 'auto'.
- Each control calls a named function in the page. Write the function if it doesn't exist.
- Keep ids short and stable, use the keys from the table, and group related controls.
- Add confirm: true to anything that resets or can't be undone.

Return the complete file, then list the controls with their keys.

4bSpeaker notes on your phone

Cues that only you can see, right under Next and Previous.

Using the Deck Remote brief, add speaker notes that show on my phone but never on screen.

- Write notes for each slide in a data-notes attribute on its section: at most 200 characters, as cues to myself rather than a script. [Or use my notes: paste them]
- Add a readout control labelled "Notes" whose value is the live slide's data-notes.

Return the complete file.

Control kinds

See every kind working in the control playground.

Set kind to one of these eight. Each one gives your page a different callback.

kindOn the phoneYour page suppliesGood for
buttona tile you taprun()one-off actions: reveal, jump, reset, play an animation
momentaryacts only while heldonPress(), onRelease()spotlight, hold-to-reveal
toggleon / off, lit when ononChange(on)theme, notes, an overlay
choicea row of optionsoptions, onChange(value)a mode, a section, a variant
numbervalue, − / + and a slidermin, max, step, onChange(n)text size, zoom, speed
texta field and SendonChange(text)a question or message on screen
timerits own card: start, pause, reset, ± 30 s, presetsseconds; optional onTick(ms), onDone()exercises and breaks (one per page)
readouta value, no inputvalue: () => 'text'something you want to see but not change

Fields every kind accepts

FieldMeaning
labelWhat the phone shows. Keep it under about 20 characters, and name the thing, not its state: "Speaker notes", not "Notes on/off".
keyA keyboard shortcut on the laptop, e.g. 'n' or 'shift+n'.
groupA folding section on the phone, e.g. 'Look'. Use groups once you have more than a handful of controls.
confirm: trueThe phone asks before firing. Use it for anything you'd regret tapping mid-talk.
iconThe tile's icon: x, one, eye, star, shuffle, note, moon, blank, timer, play, reset, jump, present.
valueThe starting value of a toggle, choice or number.

Extra fields for some kinds

  • choice: options is a list of strings, or of { value, label } objects. Add color: '#4f7cff' to an option and the phone shows a colour swatch instead of the word. compact: true lets it share a row with other tiles.
  • number: min, max, step, unit (e.g. '%').
  • text: placeholder, maxLength (up to 200). The phone adds its own × to clear the text.
  • timer: seconds, display: 'large', resetKey. The countdown appears on screen only once started, turns amber under 30 s and red under 10 s, and can be dragged and resized.

A complete example

Save this as an .html file, open it on your laptop, press Q and pair your phone. Each control changes something you can see.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Remote test</title>
  <style>
    body { font: 20px/1.5 system-ui, sans-serif; margin: 10vh auto; max-width: 40em; padding: 0 1em;
           background: #fff; color: #111; transition: background .3s, color .3s; }
    body.dark { background: #111; color: #eee; }
    #message { font-size: 2em; font-weight: 700; color: var(--accent, #2f5bea); min-height: 1.5em; }
    #answer { padding: 1em; border-radius: 12px; background: #fef3c7; color: #111; }
  </style>
</head>
<body>
  <h1>What is the capital of Australia?</h1>
  <p id="message"></p>
  <p id="answer" hidden>Canberra</p>

  <script async src="https://uxd.zennia.sg/v1/deck-remote.js"></script>
  <script>
    function startRemote() {
      DeckRemote.init({
        adapter: 'auto',
        actions: {
          answer: { kind: 'toggle', label: 'Show answer', key: 'v', icon: 'eye',
                    onChange: (on) => { document.getElementById('answer').hidden = !on; } },

          dark:   { kind: 'toggle', label: 'Dark mode', key: 'd', icon: 'moon', group: 'Look',
                    onChange: (on) => document.body.classList.toggle('dark', on) },

          accent: { kind: 'choice', label: 'Accent', group: 'Look', compact: true, value: 'blue',
                    options: [{ value: 'blue',  label: 'Blue',  color: '#2f5bea' },
                              { value: 'green', label: 'Green', color: '#16a34a' },
                              { value: 'pink',  label: 'Pink',  color: '#db2777' }],
                    onChange: (v) => document.body.style.setProperty('--accent',
                      { blue: '#2f5bea', green: '#16a34a', pink: '#db2777' }[v]) },

          size:   { kind: 'number', label: 'Text size', group: 'Look',
                    min: 80, max: 160, step: 10, value: 100, unit: '%',
                    onChange: (n) => { document.documentElement.style.fontSize = n + '%'; } },

          message: { kind: 'text', label: 'Message on screen', placeholder: 'Type a message', maxLength: 80,
                     onChange: (s) => { document.getElementById('message').textContent = s; } },

          clock:  { kind: 'timer', label: 'Thinking time', seconds: 60, display: 'large', key: 't' },
        },
      });
    }
    window.DeckRemote ? startRemote() : addEventListener('deckremote:ready', startRemote, { once: true });
  </script>
</body>
</html>

For a page using all eight kinds, see the control playground.

Pages with their own slide code

If your page already moves between slides or steps with its own code, and doesn't follow the recommended structure, give the remote a deck object instead of adapter. You then get slide numbers, titles and Jump to slide.

DeckRemote.init({
  deck: {
    next:    () => myDeck.next(),
    prev:    () => myDeck.prev(),
    goTo:    (i) => myDeck.goTo(i),        // 0-based
    current: () => myDeck.index,           // 0-based
    total:   () => myDeck.length,
    title:   (i) => myDeck.titleOf(i),
    el:      (i) => myDeck.slideElement(i), // optional: lets the phone match the slide's colour
  },
  actions: { /* your controls, as above */ },
});

All six functions from next to title are required. If one is missing, the remote switches itself off and logs the reason in the browser console. Your page keeps working.

Step 5Check and fix

5aCheck against the brief

Before you present, especially after several rounds of changes.

Check my HTML file against the Deck Remote brief, rule by rule. List each rule it breaks and why that matters. Then fix them all without changing the look or the content, and return the complete file.

[paste or attach the file]

5bSomething doesn't work

A control does nothing, Next skips around, or pressing Q doesn't show a code.

My HTML file uses Deck Remote. This isn't working: [what you did, what you expected, and what happened instead].

Here is what the browser console shows (press F12, open Console, and copy any red lines or lines starting with [deck-remote]):
[paste]

Here is the file: [paste or attach]

Find the cause and fix it, following the Deck Remote brief. Return the complete file.

Then try it for real

  1. Open the file in Chrome and press ? to check the remote has loaded.
  2. Press Q, pair your phone, and try every control while watching the screen.
  3. Walk through the whole story from your phone, the way you'll tell it.
  4. Reload the page halfway through. Your controls' values should come back.

Keyboard shortcuts

These keys belong to the remote. Don't give your own controls these keys.

No keyboard? Tap the bottom middle of the screen, then tap the bar that appears: the same list is there, and each line you can act on is a button. A hold-to-act control is the exception — a tap can't hold it down.

QUnlock, or pair a phone as the remote
Shift + QDisconnect the current phone and pair again
Enter / EscLet a waiting phone be the remote, or turn it away
?List every shortcut on this page
EscClose the overlay

Also avoid the keys your page already uses. The recommended slide template uses the arrows, Space, Page Up / Page Down, Home / End and P. If two things share a key, the remote wins and your page never sees the key press, so test every shortcut you assign.

Limits and troubleshooting

Limits

  • Up to 30 controls per page, 20 options per choice, and one timer.
  • Labels up to 40 characters; text and readout values up to 200. Longer values are cut rather than rejected.
  • A readout refreshes when the page's state changes, such as a slide change or a control being used. It doesn't tick on its own.
  • An unknown kind is drawn as a plain button.

If something doesn't work

  • On a network you don't know — a school, a client's office, a conference — open the connection check on the laptop and on the phone before you start. It says in a few seconds whether that network lets the remote through, and what to do if it doesn't.
  • Nothing happens when I press Q. Open the browser console (F12) and look for a line starting with [deck-remote]. It explains what's wrong, e.g. a missing deck function. Also check that focus isn't in a text field.
  • A control doesn't appear on the phone. Check that DeckRemote.init runs only once and that every control has a kind and a label. If the phone was paired before you edited the page, reload the page.
  • The phone can't connect. Some school and office Wi-Fi blocks live connections. Try mobile data on the phone. On the laptop, switch off VPN or iCloud Private Relay so the session is created near you.
  • The password is refused. After three wrong tries the QR code stops working. Press Q for a new one. If the phone says unlocking is paused, someone has tried too many wrong passwords this hour. Use a phone that has unlocked before, or wait for the time it shows.

Keep it private

The page is on a projector, and text and readout values travel to the phone. Don't put anything confidential in them, and never put the team password in a file.

Try itEvery control in the playground