# playhtml > playhtml makes HTML elements collaborative and real-time. Add an attribute like `can-move` or `can-toggle` to an element with an `id`, or register a custom `can-play` element, and its state syncs live between everyone on the page. Works with vanilla HTML (`playhtml` on npm or unpkg) and React (`@playhtml/react`). Read this whole file before writing playhtml code. The guide below covers the APIs, which data type to use, and the mistakes that silently break sync. playhtml makes HTML elements collaborative and real-time via Yjs CRDTs. ## The Person's Idea Drives the Build playhtml is for people making their own internet playgrounds. The experience is theirs to design; your job is to make their idea work, not to fill in the idea for them. - **Build only what was asked.** Do not add mechanics, rules, sounds, music, animations, motion, scoring, timers, themes, or extra features the person did not describe. A "musical chairs with cursors" request does not authorize you to pick the music, make cursors circle, or invent the elimination rules. - **Ask before building.** If the request leaves anything open, ask about it first. See "Before Building: One Round of Questions" below. - **Fit the page, with a lighter touch than usual.** On a page with its own style, match its character: reuse its colors, fonts, borders, illustrations, and level of playfulness, so the new element looks like it was always there. A colorful, hand-made page should get colorful, hand-made-feeling pieces, not a single-color placeholder. On a blank page, keep the styling modest and let the interaction be the interesting part. In both cases, lean a bit more restrained than you normally would: the look is the person's call, so leave room for them to make it theirs. If the request doesn't say how it should look or feel, include that in your questions. - **Offer ideas, don't ship them.** If you see a good addition, mention it in one line after the working version. The person decides. If the person says to surprise them or to use your judgment, you may make those choices, and say which ones you made. ## Before Building: One Round of Questions Before writing code, check the request against the list below. Collect everything it leaves open and ask it all in **one message**, then wait for answers. Don't ask one question at a time, and don't ask about anything the request or the existing page already answers. Make the questions easy to answer: - Group them under the headings below and number them, so the person can reply "1: a, 3: b". - Keep each one short and concrete. Offer 2–3 options when that helps. - Ask about design as seriously as about code. How it looks and feels is the person's call, not a detail to fill in. **The interaction** 1. What do people do, and what happens in response? How does it start and end? 2. When someone acts, what do others see? Live only (cursors, presence), traces left for later visitors, or both? 3. What happens when only one person is on the page? **The look** 4. Should it match the page's existing style or have its own? Any mood, colors, or references? 5. Where does it sit on the page, and how big is it? Should anything move or animate? **The data** (these decide which API and data type to use; getting them wrong means a rewrite) 6. Should it survive a page refresh? (`defaultData` = yes, presence = no) 7. Does everyone see the same state, or does each person have their own? 8. Vanilla HTML or React? If nothing is open, skip the questions. For anything bigger than a single element, still restate the plan in a few plain sentences and get a yes before writing code. ## Data Types | Type | Persists? | Syncs? | Use for | |------|-----------|--------|---------| | `defaultData` | Yes | Yes | Positions, counts, messages, toggles | | presence: `defaultPresence` (element) / `playhtml.people.setMyPresence` (page) | No | Yes | Per-person typing, ready, hover, or selection state | | `dispatchPlayEvent` | No | One-shot | Confetti, notifications | | `localStorage` | Yes | No | Per-user flags ("has reacted") | People: every person is a `Person` (`{ pid, name, color, isMe, presence }`). `playhtml.people.everyone` is everyone on the page including you (filter `!person.isMe` for others); `playhtml.people.me` is you (assign `me.name` / `me.color` to save and show them). Key per-person data by `pid`. Page presence: `playhtml.people.setMyPresence(key, value)` sets one key (`null` clears it), `playhtml.people.onChange(keys?, cb)` fires now and on changes (skips cursor moves unless `"cursor"` is in keys). Cursors are at `person.presence.cursor`. `playhtml.people` is available after `playhtml.ready`. Rooms: `playhtml.createPresenceRoom(name).people`, same API. React: `usePeople(keys?)` → `{ everyone, me, setMyPresence }`, also on `usePlayContext().people`. Elements use the same names: `defaultPresence`, and `everyone` / `me` / `setMyPresence(value | mutator)` in callbacks and on handles (`handle.onEveryoneChange(keys?, cb)`). Deprecated but working: `playhtml.users`, `User`, `playhtml.presence`, `useUsers`, `usePresence`, `useCursorPresences`, `usePlayerIdentity`, element `live`/`users`/`setLive`. ## Critical Rules - Every element MUST have a unique `id` attribute — without it, sync silently fails - Vanilla HTML: `import { playhtml } from "https://unpkg.com/playhtml@latest"` only works inside ` ``` Every other vanilla snippet in this guide that uses `playhtml` goes inside the same `