Capabilities

Every capability in playhtml is a single HTML attribute. Slap it on an element, give the element an id, and the library handles sync, persistence, and event wiring. This page catalogs the eight built-ins plus can-play, in order from most-commonly used to most-specialized.

Every playhtml element needs a stable id

The id is the key an element’s synced data is stored under, so it must be stable across reloads and browsers. That’s how two visitors agree on which element is which. A hand-written id="my-lamp" is ideal. If you omit it, playhtml falls back to hashing the element’s HTML, which can differ across browsers and break sync.

For many elements that share a selector (a row of magnets, a list of reactions), give each the same markup and add a single selector-id attribute instead of inventing unique ids. playhtml indexes the matches by position, so the N-th .magnet always gets the N-th slot of state. See Dynamic elements.

Shift-click to reset

The built-in interactive capabilities (can-move, can-spin, can-toggle, and can-grow) support shift-clicking an element to reset it to its default state. Because the state is shared, this resets it for everyone in the room (a moved element snaps back to its origin, a spun one to 0°, a toggle to off, a grown one to scale 1). Custom can-play elements can opt into this with the resetShortcut option.

Every section below has the same shape:

• A short description of what the capability does and the kind of state it owns.
• A live demo you can interact with. Open the page in a second tab and watch both update.
• The vanilla HTML form, and the React form. Pick the framework you’re shipping in; the reader’s choice syncs across every snippet on the page.

This page also runs a few can-play demos directly in its margins: a doodle strip below, a guestbook further down, a prize wheel at the bottom, and a shared tally on every code block you copy from. They’re discussed properly in the can-play section.

CAN-PLAY · doodle strip

Draw a tiny 64×64 face. It joins the strip for everyone reading this page. Capped at 20.

can-move

What it does. Drag anywhere. Position persists and syncs.

Use it for: drag-and-drop affordances such as fridge magnets, game pieces, arrangeable stickers, a puzzle.

Vanilla HTML

<div id="arena" style="position: relative; height: 320px;">
  <img can-move can-move-bounds="arena" id="hat" src="/yankees-hat.png" alt="" />
  <img can-move can-move-bounds="arena" id="cat" src="/long-cat.png" alt="" />
</div>

React

import { CanMoveElement } from "@playhtml/react";

<div id="arena" style={{ position: "relative", height: 320 }}>
  <CanMoveElement bounds="arena">
    <img id="hat" src="/yankees-hat.png" alt="" />
  </CanMoveElement>
  <CanMoveElement bounds="arena">
    <img id="cat" src="/long-cat.png" alt="" />
  </CanMoveElement>
</div>

Constraining the drag area

Use can-move-bounds (vanilla) or the bounds prop (React) to keep the element inside a container. The value is an element id (with or without the leading #) or any valid CSS selector.

Vanilla HTML

<div id="fridge" style="position: relative; height: 400px;">
  <div can-move can-move-bounds="fridge" id="magnet-a">🍎</div>
  <div can-move can-move-bounds="#fridge" id="magnet-b">🥐</div>
</div>

React

import { CanMoveElement } from "@playhtml/react";

<div id="fridge" style={{ position: "relative", height: 400 }}>
  <CanMoveElement bounds="fridge">
    <div id="magnet-a">🍎</div>
  </CanMoveElement>
  <CanMoveElement bounds="#fridge">
    <div id="magnet-b">🥐</div>
  </CanMoveElement>
</div>

The cursor can go past the container edge; only the element’s position is clamped. By default, the keep-visible slice is max(25% of element size, 60px) on every edge, so readers always have something to grab. Two knobs let you tune that:

• can-move-bounds-min-visible / boundsMinVisible: fraction (0–1) of the element to keep inside. 1 pins fully inside (strict clamp); 0 drops the fraction constraint entirely.
• can-move-bounds-min-visible-px / boundsMinVisiblePx: absolute pixel floor. Useful when an image has transparent padding around its paint; a pure fraction of the layout bbox can let the visible pixels clip into invisible border.

The effective slice on each axis is max(fraction × size, pxFloor). Set both to 0 to opt fully out of the keep-visible guarantee and let the element slip entirely out of view.

Vanilla HTML

<!-- Keep 50% of the magnet inside the fridge, ignoring the px floor -->
<div can-move can-move-bounds="fridge"
     can-move-bounds-min-visible="0.5"
     can-move-bounds-min-visible-px="0"
     id="magnet">
  🧲
</div>

<!-- Small magnet: fraction of 0.25 × 40px = 10px is too small to grab.
     The 60px default floor keeps the whole magnet visible regardless. -->
<div can-move can-move-bounds="fridge" id="tiny-magnet" style="width: 40px;">
  🌶️
</div>

React

import { CanMoveElement } from "@playhtml/react";

{/* Keep 50% of the magnet inside the fridge, ignoring the px floor */}
<CanMoveElement bounds="fridge" boundsMinVisible={0.5} boundsMinVisiblePx={0}>
  <div id="magnet">🧲</div>
</CanMoveElement>

{/* Small magnet: the 60px default floor keeps the whole magnet visible. */}
<CanMoveElement bounds="fridge">
  <div id="tiny-magnet" style={{ width: 40 }}>🌶️</div>
</CanMoveElement>

can-toggle

What it does. Click to flip an on/off boolean. Persists and syncs.

Use it for: shared switches, lamps, “is-this-thing-open” signs, per-element read/unread state. The playhtml homepage uses this on the wordmark letters and the hanging lamp; click either to flip it for everyone.

Vanilla HTML

<button id="my-switch" class="switch" can-toggle>off</button>

<style>
  .switch.toggled { background: #6cd97e; }
  .switch.toggled::after { content: "on"; }
</style>

can-toggle adds the toggled class when the element is on. The older clicked class is still applied for existing styles.

React

import { CanToggleElement } from "@playhtml/react";

<CanToggleElement>
  {({ data }) => {
    const on = typeof data === "object" ? data.on : !!data;
    return (
      <button
        id="my-switch"
        type="button"
        className={on ? "is-on" : "is-off"}
        aria-pressed={on}
      >
        {on ? "on" : "off"}
      </button>
    );
  }}
</CanToggleElement>

CanToggleElement already wires up the click handler. Don’t add your own onClick, or you’ll toggle twice per click. Render declaratively from data.

can-grow

What it does. Click to scale up. Alt-click (or equivalent modifier) to scale down. Persists and syncs.

Use it for: zoomable images, inflating a balloon or sticker, growing a banner over time.

Vanilla HTML

<img can-grow id="balloon" src="/water-balloon.png" alt="" />

React

import { CanPlayElement } from "@playhtml/react";
import { TagType } from "playhtml";

<CanPlayElement tagInfo={[TagType.CanGrow]} id="balloon" defaultData={{ scale: 1 }}>
  {() => <img src="/water-balloon.png" alt="" />}
</CanPlayElement>

can-spin

What it does. Drag to rotate. Persists and syncs.

Use it for: wheels, dials, gauges, spinnable stickers or album covers, “what’s your answer” wheels.

Vanilla HTML

<img can-spin id="wheel" src="/bike-wheel.webp" alt="" />

React

import { CanPlayElement } from "@playhtml/react";
import { TagType } from "playhtml";

<CanPlayElement tagInfo={[TagType.CanSpin]} id="wheel" defaultData={{ rotation: 0 }}>
  {() => <img src="/bike-wheel.webp" alt="" />}
</CanPlayElement>

can-hover

What it does. Shares hover state across everyone on the page. Presence-based, not persistent: when a user leaves, their hover clears.

Use it for: “who’s looking at this right now” affordances, social read-receipts, zero-latency shared hover effects.

How it works. While anyone (you or another reader) is hovering the element, playhtml sets a data-playhtml-hover attribute on it; when nobody is hovering, the attribute is removed. Style the effect by targeting [data-playhtml-hover] instead of the :hover pseudo-class. That’s the only change from a normal hover style, and it’s the same attribute whether you use the vanilla capability or the React component.

Vanilla HTML

<div can-hover id="hover-pad">hover me</div>

<style>
  /* Use [data-playhtml-hover], NOT :hover, so the effect fires
     for everyone when anyone on the page hovers the element. */
  #hover-pad[data-playhtml-hover] {
    background: #fde047;
    transform: scale(1.05);
  }
</style>

React

import { CanHoverElement } from "@playhtml/react";

<CanHoverElement>
  <div id="hover-pad">hover me</div>
</CanHoverElement>

/* Same attribute as the vanilla capability */
#hover-pad[data-playhtml-hover] {
  background: #fde047;
  transform: scale(1.05);
}

If you want the hover effect to reflect who is hovering (e.g. tint the element with each viewer’s cursor color) rather than a plain on/off, read the hover roster off awareness with a custom can-play element:

import { CanPlayElement } from "@playhtml/react";
import { TagType } from "playhtml";

<CanPlayElement
  tagInfo={[TagType.CanHover]}
  id="hover-pad"
  defaultData={{}}
  myDefaultAwareness={"#3b82f6"}
>
  {({ awareness }) => (
    <div
      style={{
        background: `linear-gradient(45deg, ${awareness.join(", ")})`,
      }}
    >
      hover me
    </div>
  )}
</CanPlayElement>

can-duplicate

What it does. Click a trigger to clone an existing element into a new one. Every clone is independent shared state.

Use it for: user-generated galleries, seed-from-template UIs, stamps, “leave your mark” patterns.

Vanilla HTML

<img id="bunny-template" src="/pixel-bunny.png" alt="" />
<button can-duplicate="bunny-template" id="clone-btn">clone a bunny</button>

<script>
  // The "reset" button sweeps every spawned rabbit from shared state.
  // Clones get an id of the form "bunny-template-<random>", so match on that prefix.
  document.getElementById("reset-btn").addEventListener("click", () => {
    document.querySelectorAll("[id^='bunny-template-']").forEach((el) => {
      playhtml.deleteElementData("can-duplicate", el.id);
      el.remove();
    });
  });
</script>
<button id="reset-btn">reset</button>

By default, clones are inserted right after the template (or the previous clone). Add can-duplicate-to (an element id or CSS selector) to drop every clone into a specific container instead:

<button
  can-duplicate="bunny-template"
  can-duplicate-to="#bunny-pen"
  id="clone-btn"
>clone a bunny</button>
<div id="bunny-pen"></div>

React

import { useRef } from "react";
import { CanDuplicateElement } from "@playhtml/react";

// CanDuplicateElement takes refs, not selectors. `elementToDuplicate` is the
// template that gets cloned; `canDuplicateTo` is the React equivalent of the
// can-duplicate-to attribute. Both elements need a stable `id`.
function BunnyField() {
  const template = useRef<HTMLDivElement>(null);
  const field = useRef<HTMLDivElement>(null);

  return (
    <div>
      <div id="bunny-template" ref={template}>🐰</div>
      <div id="bunny-field" ref={field} />
      <CanDuplicateElement elementToDuplicate={template} canDuplicateTo={field}>
        <button>clone a bunny</button>
      </CanDuplicateElement>
    </div>
  );
}

can-mirror

What it does. A meta-capability: can-mirror auto-syncs every attribute, child-node change, and form-state change on the element. You don’t write defaultData, setData, or an updateElement callback; the library observes the DOM for you.

Use it for: when the state you want to share is the DOM: a shared textarea, a form, a growing list of children.

Vignette A: an emoji-only textarea

A textarea that filters to emoji characters on input. The filtered value mirrors to everyone.

Type anything. Only emojis stick, and the filtered value mirrors to everyone.

<textarea can-mirror id="emoji-pad" rows="4" placeholder="emojis only..."></textarea>

<script>
  const emojiOnly = /\p{Extended_Pictographic}/gu;
  document.getElementById("emoji-pad").addEventListener("input", (e) => {
    const match = e.target.value.match(emojiOnly);
    e.target.value = match ? match.join("") : "";
  });
</script>

Vignette B: a list you can add children to

Click ”+” to append a new <li>. The child addition itself mirrors, so new readers see the whole list, not just the latest.

• first

add entry

<ul can-mirror id="guestbook">
  <li>first</li>
</ul>
<button onclick="
  document.getElementById('guestbook').appendChild(
    Object.assign(document.createElement('li'), { textContent: new Date().toLocaleTimeString() })
  );
">add entry</button>

Experimental

can-mirror is the newest capability and still evolving. If you need full control over the shape of shared state (e.g. to enforce limits, migrate schemas, or derive values from mutations), reach for can-play instead.

PlaygroundSee every can-mirror edge case →

Hover, focus, every form input, contenteditable, programmatic attribute changes: one page with a live demo for each. Open in two tabs to watch it sync.

CAN-PLAY · guestbook

Drop a note about what you’re learning or building. The list is shared, capped at 20, oldest entries fall off.

can-play

What it does. The “build your own capability” escape hatch. You define defaultData, onClick / onDrag / onMount handlers, and an updateElement callback. playhtml syncs the data and fires your handlers.

Use it for: anything the built-ins don’t already cover. Custom counters, guestbooks, chat, games, reactions, per-user state, event-based broadcasts.

Most capability tags can share the same element. Each tag keeps its own data and behavior, so an element can be both custom and draggable with <img can-play can-move id="candle">. Watch out for style conflicts: two capabilities can still fight if they write the same CSS property. For example, can-move and can-spin both update transform, so the last update wins instead of combining translate and rotate automatically.

This page is itself a can-play showcase. Four examples live in the margins:

• Doodle strip: freehand canvas input encoded as a tiny PNG data URL. The shared array caps at 20 via splice inside the setData mutator.
• Guestbook: a growing list of short text entries. Same “cap the array” pattern, different payload.
• Prize wheel: one shared piece of data (the spin seed + target) animates identically on every tab. Every visitor sees the wheel land on the same label.
• Tally on every code block: every <pre> on this page is a vanilla can-play element. Click copy on any snippet and watch a tally tick appear next to the button. Readers all over the site share that counter, so popular snippets accumulate more marks.

That’s four different shapes (short array, blob payload, animation seed, single integer) built on the same primitive. The minimum viable shape is much smaller, though:

Vanilla HTML

<button can-play id="cheer" data-count="0">❤️ <span>0</span></button>

<script>
  const el = document.getElementById("cheer");
  el.defaultData = { count: 0 };
  el.onClick = (_e, { setData }) => {
    setData((draft) => {
      draft.count += 1;
    });
  };
  el.updateElement = ({ element, data }) => {
    element.querySelector("span").textContent = data.count;
  };
</script>

React

import { withSharedState } from "@playhtml/react";

export const CheerButton = withSharedState(
  { defaultData: { count: 0 }, id: "cheer" },
  ({ data, setData }) => (
    <button
      onClick={() => {
        setData((draft) => {
          draft.count += 1;
        });
      }}
    >
      ❤️ {data.count}
    </button>
  ),
);

Counters should use the mutator form of setData. It applies the increment to the draft at write time instead of copying a rendered data snapshot back into shared data. The same idea applies to pushing list entries, updating nested fields, and upserting keyed collections; see Merging data changes.

Deeper material on custom capabilities lives in Data essentials and Dynamic elements.

Resetting custom elements

The built-in interactive capabilities support shift-click to reset (see the tip at the top of this page). Opt your own can-play element into the same gesture with resetShortcut, a modifier key that, when held while clicking, restores the element’s defaultData for everyone:

el.defaultData = { count: 0 };
el.resetShortcut = "shiftKey"; // "shiftKey" | "ctrlKey" | "altKey" | "metaKey"

In React, pass it in the config:

withSharedState(
  { defaultData: { count: 0 }, id: "cheer", resetShortcut: "shiftKey" },
  ({ data, setData }) => /* … */,
);

You can also reset programmatically by calling element.reset().

---

Composed examples

These capabilities are the building blocks. The best way to see them in concert is to visit the live experiments room, where readers leave permanent marks in a shared space.

EXPERIMENT · 04Every colorA page where every visitor adds one color. can-play + per-user awareness + an ever-growing shared palette.COMMUNITY · FRIDGEFridge poetrycan-move + can-play + selector-id. Arrange magnets with strangers. Saves forever.EXPERIMENT · 05Minute faces (together)1,440 minutes in a day, one color per minute. Paint the clock with everyone who shows up that minute.

These three are highlighted in the homepage experiments index, the fastest way to see playhtml at room-scale.

CAN-PLAY · prize wheel

Spin to pick a docs page to read next. The wheel’s spin seed is shared, so everyone here sees it land on the same label.