playhtml

https://playhtml.fun/docs
Admin
playhtml turns any HTML element into a live, shared one with a single attribute — no backend...
Tokens:28,362
Snippets:304
Trust Score:6.9
Update:4 months ago
Show doc for...
Tokens:
Raw
### React: Install PlayHTML Packages

Source: https://playhtml.fun/docs/getting-started

Install the necessary PlayHTML packages for React integration. This includes the React components and common utilities.

```bash
npm install @playhtml/react @playhtml/common
```

--------------------------------

### CanPlayElement Usage Example

Source: https://playhtml.fun/docs/reference/react-api

Example demonstrating the usage of CanPlayElement with tagInfo, id, defaultData, and a children render prop to create an interactive button.

```jsx
<CanPlayElement
  tagInfo={[TagType.CanToggle]}
  id="my-lamp"
  defaultData={{ on: false }}>
  {({ data, setData }) => (
    <button onClick={() => setData({ on: !data.on })}>
      {data.on ? "on" : "off"}
    </button>
  )}
</CanPlayElement>
```

--------------------------------

### Vanilla HTML PlayHTMl API Examples

Source: https://playhtml.fun/docs/integrations/building-with-ai

Examples of key PlayHTMl APIs for vanilla JavaScript, including setting default data, handling clicks, and updating elements.

```javascript
element.defaultData = { ... } // Initial state (REQUIRED)
```

```javascript
element.onClick = (e, { data, setData }) => { ... } // Handle clicks
```

```javascript
element.onDrag = (e, { data, setData }) => { ... } // Handle drag
```

```javascript
element.onMount = ({ getData, setData, element }) => { ... } // Setup logic
```

```javascript
element.updateElement = ({ element, data }) => { ... } // Update DOM when data changes (REQUIRED)
```

```javascript
element.resetShortcut = "shiftKey" // Keyboard reset
```

--------------------------------

### React Setup for PlayHTMl

Source: https://playhtml.fun/docs/integrations/building-with-ai

Set up a React application to use PlayHTMl by wrapping components in PlayProvider. This enables real-time collaboration features.

```javascript
import { PlayProvider } from "@playhtml/react";

function App() {
  return (
    <PlayProvider>
      <MyPlayhtmlComponent />
    </PlayProvider>
  );
}
```

--------------------------------

### Vanilla HTML Setup for PlayHTMl

Source: https://playhtml.fun/docs/integrations/building-with-ai

Configure element properties and initialize PlayHTMl for vanilla JavaScript projects. Ensure all custom properties are set before calling playhtml.init().

```javascript
const element = document.getElementById("myElement");

element.defaultData = { /* ... */ };
element.onClick = (e, { data, setData }) => { /* ... */ };
element.updateElement = ({ data }) => { /* ... */ };

import { playhtml } from "https://unpkg.com/playhtml";
playhtml.init();
```

--------------------------------

### Install PlayHTML React Package

Source: https://playhtml.fun/docs/using-react

Install the PlayHTML React package using npm. This package is compatible with React versions 16.8 and above.

```bash
npm install @playhtml/react
```

--------------------------------

### Distance-based Cursor Styling Example

Source: https://playhtml.fun/docs/data/presence/cursors

An example of customizing cursor styles based on the distance from the current user's cursor.

```javascript
getCursorStyle: (presence) => {
  const distance = Math.sqrt(
    Math.pow(presence.cursor.x - myX, 2) +
    Math.pow(presence.cursor.y - myY, 2)
  );

  if (distance > 500) {
    return { opacity: '0.3' };
  }
  return {};
}
```

--------------------------------

### NPM Install for Bundler Integration

Source: https://playhtml.fun/docs/getting-started

Install the playhtml package using npm when you are using a bundler in your project. This makes the playhtml library available for import.

```bash
npm install playhtml
```

--------------------------------

### Vanilla HTML: Drop-in Script Setup

Source: https://playhtml.fun/docs/getting-started

Use this method for the quickest integration without any build steps or module syntax. Place the script tag at the end of your body to ensure all interactive elements are present when the script runs.

```html
<body>
  <button id="my-lamp" can-toggle>lamp</button>

  <script type="module" src="https://unpkg.com/playhtml/init.js"></script>
</body>
```

--------------------------------

### Initialize PlayHTML with React Components

Source: https://playhtml.fun/docs

This snippet demonstrates how to set up PlayHTML within a React application using the PlayProvider and CanToggleElement components. Install the necessary packages before use.

```jsx
// npm install @playhtml/react @playhtml/common
import { PlayProvider, CanToggleElement } from "@playhtml/react";

<PlayProvider>
  <CanToggleElement>
    <img id="lamp" src="/noguchi-hanging-lamp.png" />
  </CanToggleElement>
</PlayProvider>
```

--------------------------------

### withSharedState Props-Dependent Config Example

Source: https://playhtml.fun/docs/reference/react-api

Example of using a callback for the config in withSharedState when defaultData needs to derive from props.

```jsx
export const Reaction = withSharedState(
  ({ reaction: { count } }) => ({ defaultData: { count } }),
  ({ data, setData }, props) => /* … */,
);
```

--------------------------------

### Add custom capabilities

Source: https://playhtml.fun/docs/reference/init-options

Ship your own 'can-*' capability alongside built-ins. This example adds a 'can-pulse' capability that toggles a CSS class on click.

```javascript
playhtml.init({
  extraCapabilities: {
    "can-pulse": {
      defaultData: { on: false },
      updateElement: ({ element, data }) => {
        element.classList.toggle("pulsing", data.on);
      },
      onClick: (_e, { data, setData }) => setData({ on: !data.on }),
    },
  },
});
```

--------------------------------

### Shared Guestbook List with can-mirror

Source: https://playhtml.fun/docs/capabilities

This example creates a shared guestbook list where new entries are appended to a `<ul>` element. New list items are mirrored to all clients.

```html
<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>
```

--------------------------------

### Minimal Cursor Opt-in

Source: https://playhtml.fun/docs/reference/init-options

Enables multiplayer cursors with the most basic configuration. Use this for a quick setup to test cursor functionality.

```javascript
playhtml.init({ cursors: { enabled: true } });
```

--------------------------------

### React PlayHTMl API Examples with SharedState

Source: https://playhtml.fun/docs/integrations/building-with-ai

Examples of using PlayHTMl's withSharedState HOC in React for managing shared state and rendering components.

```javascript
withSharedState({ defaultData: {...} }, ({ data, setData, ref }) => JSX)
```

--------------------------------

### Basic Shared Element Example

Source: https://playhtml.fun/docs/advanced/shared-elements

Define a shared element on the source page and reference it on a consumer page. The consumer can have different markup and styles.

```html
<!-- Source page (thissite.com) -->
<div id="couch" shared can-move style="font-size: 80px">🛋</div>

<!-- Consumer page (anothersite.com) -->
<div data-source="thissite.com#couch" can-move>🪑</div>
```

--------------------------------

### Handle connection errors

Source: https://playhtml.fun/docs/reference/init-options

Provide a callback for connection failures. This example adds a CSS class to the body and logs a warning to the console.

```javascript
playhtml.init({
  onError: () => {
    document.body.classList.add("playhtml-offline");
    console.warn("playhtml could not connect");
  },
});
```

--------------------------------

### React can-duplicate setup

Source: https://playhtml.fun/docs/capabilities

React wiring for 'can-duplicate' typically pairs with setupPlayElement to register freshly-mounted clones. Refer to 'Dynamic elements' documentation for more details.

```jsx
// React wiring for can-duplicate typically pairs with setupPlayElement
// so freshly-mounted clones register themselves. See "Dynamic elements".
```

--------------------------------

### Enable Cursors in JavaScript

Source: https://playhtml.fun/docs/data/presence/cursors

Initialize Playhtml with cursor tracking enabled. This is the basic setup for JavaScript applications.

```javascript
import { playhtml } from "playhtml";

playhtml.init({
  cursors: {
    enabled: true,
  }
});
```

--------------------------------

### Example: Delete word and its data

Source: https://playhtml.fun/docs/data/data-essentials

Demonstrates deleting a word from local state and then cleaning up its associated PlayHTML data using `deleteElementData`.

```typescript
function handleDeleteWord(id: string) {
  setWords((prev) => prev.filter((w) => w.id !== id));

  if (window.playhtml) {
    window.playhtml.deleteElementData("can-move", id);
  }
}
```

--------------------------------

### Flat Data Shaping Example

Source: https://playhtml.fun/docs/data/data-essentials

Illustrates good practice for data shaping by keeping object structures flat to improve performance and reduce conflicts. Avoids deep nesting.

```javascript
// Good
defaultData: { x: 0, y: 0, color: "#ff0000", size: 100 }

// Acceptable (one level, fields are clearly related)
defaultData: { position: { x: 0, y: 0 }, color: "#ff0000" }

// Avoid
defaultData: {
  position: { coords: { x: 0, y: 0 } },
  style: { appearance: { color: "#ff0000" } },
}
```

--------------------------------

### Install Claude Code Plugin for Playhtml

Source: https://playhtml.fun/docs/integrations/building-with-ai

Install the playhtml plugin for Claude Code to enable automatic skill activation when building playhtml elements. This plugin handles APIs, data types, and common mistakes.

```bash
claude plugin marketplace add spencerc99/playhtml
```

```bash
claude plugin install playhtml@playhtml
```

--------------------------------

### React: Basic Toggle Component Setup

Source: https://playhtml.fun/docs/getting-started

Wrap your application tree with `PlayProvider` and use the `CanToggleElement` component for a shared toggle functionality. Cursors are enabled via `initOptions`.

```javascript
import { PlayProvider, CanToggleElement } from "@playhtml/react";

export function App() {
  return (
    <PlayProvider initOptions={{ cursors: { enabled: true } }}>
      <CanToggleElement>
        <button id="my-lamp">lamp</button>
      </CanToggleElement>
    </PlayProvider>
  );
}
```

--------------------------------

### Getting Own Identity

Source: https://playhtml.fun/docs/data/presence

Retrieve the identity information for the current local user.

```javascript
const me = playhtml.presence.getMyIdentity();
```

--------------------------------

### Declare inline event listeners

Source: https://playhtml.fun/docs/reference/init-options

Declare event listeners directly at initialization time for events that should always be registered. This example sets up a 'confetti' event.

```javascript
playhtml.init({
  events: {
    confetti: {
      type: "confetti",
      onEvent: () => window.confetti({ particleCount: 100 }),
    },
  },
});
```

--------------------------------

### Accessing Cursors from Play Context

Source: https://playhtml.fun/docs/reference/react-api

Shows how to access the cursors object from the Play HTML context. Provides examples of accessing cursor properties like allColors, color, and name.

```jsx
const { cursors } = usePlayContext();
// cursors.allColors: string[]
// cursors.color: string
// cursors.name: string
```

--------------------------------

### Domain-Wide Count, Page-Specific Cursors

Source: https://playhtml.fun/docs/data/presence/cursors

Configure cursors to show a domain-wide user count while only rendering cursors from the current page. This setup uses the 'domain' room for global presence.

```javascript
playhtml.init({
  cursors: {
    enabled: true,
    room: "domain",  // All pages share presence
    shouldRenderCursor: (presence) => {
      // Only render same-page cursors
      return presence.page === window.location.pathname;
    }
  }
});

// Access global count
const totalUsers = window.cursors.allColors.length;
```

```jsx
<PlayProvider
  initOptions={{
    cursors: {
      enabled: true,
      room: "domain",
      shouldRenderCursor: (presence) =>
        presence.page === window.location.pathname
    }
  }}>
  <UserCount />  {/* Shows domain-wide count */}
  {/* Cursors only appear from same page */}
</PlayProvider>

function UserCount() {
  const { cursors } = usePlayContext();
  return <div>👥 {cursors.allColors.length} online</div>;
}
```

--------------------------------

### Manage Element State with CanPlayElement

Source: https://playhtml.fun/docs/using-react

Use `<CanPlayElement>` to manage the state of a specific DOM element, providing access to `data` and `setData`. This example creates a toggleable button.

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

<CanPlayElement
  tagInfo={[TagType.CanToggle]}
  id="my-lamp"
  defaultData={{ on: false }}>
  {({ data, setData }) => (
    <button onClick={() => setData({ on: !data.on }) }>
      {data.on ? "on" : "off"}
    </button>
  )}
</CanPlayElement>;
```

--------------------------------

### Modifying Element Class and Attribute via Console

Source: https://playhtml.fun/docs/advanced/mirror-playground

This example shows how to manipulate an element's class list and attributes using JavaScript in the browser console. These changes are then mirrored to other clients connected to the same 'can-mirror' session.

```javascript
const el = document.querySelector("#pg-mirror-hover");
el.classList.add("is-flag");
el.setAttribute("data-you-changed-this", "yes");
```

--------------------------------

### Initialize playhtml with basic options

Source: https://playhtml.fun/docs/reference/init-options

Basic initialization of playhtml with room and cursor settings. Pass options to playhtml.init() or PlayProvider.

```javascript
import { playhtml } from "playhtml";

playhtml.init({
  room: "my-room",
  cursors: { enabled: true },
  // …
});
```

--------------------------------

### Wrap App with PlayProvider

Source: https://playhtml.fun/docs/using-react

Wrap your React application's root with `<PlayProvider>` to initialize the PlayHTML client and establish a connection. Pass any necessary initialization options to `initOptions`.

```jsx
import { PlayProvider } from "@playhtml/react";

export default function App() {
  return (
    <PlayProvider
      initOptions={{
        // room: "my-room",
        // cursors: { enabled: true },
      }}>
      <YourApp />
    </PlayProvider>
  );
}
```

--------------------------------

### PlayProvider

Source: https://playhtml.fun/docs/reference/react-api

Initializes the playhtml client for a React subtree. There must be exactly one PlayProvider per React root.

```APIDOC
## `<PlayProvider>`

### Description
Initializes the playhtml client for a React subtree. There must be exactly one `PlayProvider` per React root.

### Props
- **initOptions** (InitOptions) - Optional - Options for initializing the playhtml client.
- **pathname** (string) - Optional - The current pathname, used for client-side navigation.
- **children** (React.ReactNode) - Required - The child elements to be rendered within the provider.

### Example
```jsx
import { PlayProvider } from "@playhtml/react";

<PlayProvider initOptions={{ cursors: { enabled: true } }}>
  <App />
</PlayProvider>;
```
```

--------------------------------

### Combining Shared and Local Capabilities

Source: https://playhtml.fun/docs/advanced/shared-elements

Showcases how a consumer can have both synchronized shared capabilities and local-only capabilities.

```html
<!-- Source shares movement -->
<div id="lamp" shared can-move>💡</div>

<!-- Consumer adds local toggle; only movement is synchronized -->
<div data-source="thissite.com#lamp" can-move can-toggle class="rounded"></div>
```

--------------------------------

### Shared Element Permissions

Source: https://playhtml.fun/docs/advanced/shared-elements

Demonstrates how to set read-only permissions for shared elements on the source and how consumers can enforce local read-only behavior.

```html
<!-- Source declares read-only -->
<div id="status" shared="read-only" can-toggle>🔒</div>

<!-- Consumer: auto-read-only based on source; local writes are blocked -->
<div data-source="thissite.com#status" can-toggle></div>

<!-- Consumer: force local read-only even if source is read-write -->
<div data-source="thissite.com#couch" data-source-read-only can-move>🪑</div>
```

--------------------------------

### PlayProvider Initialization

Source: https://playhtml.fun/docs/reference/react-api

Initializes the PlayHTMl client for a React subtree. Ensure exactly one PlayProvider per React root. initOptions map to playhtml.init() arguments.

```typescript
interface PlayProviderProps {
  initOptions?: InitOptions;
  pathname?: string;
  children: React.ReactNode;
}
```

```jsx
import { PlayProvider } from "@playhtml/react";

<PlayProvider initOptions={{ cursors: { enabled: true } }}>
  <App />
</PlayProvider>;
```

--------------------------------

### Initialize PlayHTML in Vanilla HTML

Source: https://playhtml.fun/docs

This snippet shows how to initialize PlayHTML in a standard HTML file using a script tag. Ensure the script is placed where it can access the DOM elements.

```html
<script type="module">
  import { playhtml } from "https://unpkg.com/playhtml";
  playhtml.init();
</script>
<img can-toggle id="lamp" src="/noguchi-hanging-lamp.png" />
```

--------------------------------

### Basic HTML Structure

Source: https://playhtml.fun/docs/play

The foundational HTML document for the playhtml starter. It includes meta tags, title, and basic CSS styling for layout and appearance.

```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>playhtml starter</title>
<style>
:root {
--color-bg: #69f7be;
--color-primary: #ffff00;
--font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
}
* { box-sizing: border-box; }
body { font-family: var(--font-family); background-color: var(--color-bg); margin: 0; padding: 1rem; }
.wrapper { min-height: 87vh; display: grid; place-items: center; margin: 0 1rem; }
.content { display: flex; flex-direction: column;
align-items: center; justify-content: center; }
.title { color: #2800ff; font-weight: 700; font-size: 64px; line-height: 1.05; margin: 0 0 1rem; }
.illustration { max-width: 100%; max-height: 240px; margin-top: 2rem; }
.instructions { margin: 1rem auto 0; }
button, input { font-family: inherit; font-size: 100%; background: #ffffff; border: 1px solid #000; padding: 0.5rem 1rem; transition: 500ms; }
h2 { color: #2800ff; }
.illustration:active { transform: translateY(5px); }
.dipped { transform: translateY(5px); }
#lamp.clicked { filter: brightness(1.2) saturate(1.6) drop-shadow(0px 0px 50px rgba(247, 220, 156, 0.85)); }
.highlighted { box-shadow: 0px 0px 30px 10px rgb(245, 169, 15) !important; background: rgb(245 169 15 / 80%); }
.capabilities li { width: fit-content; cursor: zoom-in; padding: 4px 0; }
.capabilities li:hover { text-shadow: 0px 0px 4px rgb(245, 169, 15); }
#colorBox { width: 200px; height: 60px; margin-bottom: 10px; background-color: white; display: block; }
#shootingStar { top: -36px; left: -36px; font-size: 36px; position: fixed; text-shadow: 0 0 4px yellow; }
#catOrDog { width: 200px; }
#catOrDog.clicked { content: url("https://playhtml.fun/playground-starter/dog.png"); }
#plant { width: 200px; }
#hoverBox.hovered { background: blue !important; transform: scale(1.1); }
.reaction { transition: all 0.2s ease; cursor: pointer; }
.reaction.reacted { background: #ff6b6b; transform: scale(1.05); box-shadow: 0 5px 15px rgba(255, 107, 107, 0.3); }
</style>
</head>
<body>
<div class="wrapper">
<div class="content" role="main">
<h1 class="title" id="title">Hello World!</h1>
<img src="https://playhtml.fun/playground-starter/illustration.svg" class="illustration" alt="Editor illustration" title="Click the image!" id="illustration" can-spin />
  

<div class="instructions">
<img src="https://playhtml.fun/playground-starter/open-sign.gif" can-move id="openSign" />
<img src="https://playhtml.fun/playground-starter/lamp.png" style="width: 200px; position: absolute; top:0; right: -16px" id="lamp" can-toggle />
  
<div style="margin-bottom: 2em; gap: 2em; display: flex; flex-wrap: wrap; align-items: center;">
<img id="catOrDog" src="https://playhtml.fun/playground-starter/cat.jpg" can-toggle/>
<img id="plant" can-grow src="https://playhtml.fun/playground-starter/plant.png"/>
<div id="hoverBox" can-hover style="width: 100px; height: 100px; background: red;"></div>
<button id="duplicateBtn" can-duplicate style="font-size: 24px; padding: 10px 20px;">Click to clone me!</button>
</div>
  
<input id="colorBox" can-mirror/>
<button id="btn" can-mirror>CHANGE COLOR</button>
  
<h2>playhtml starter</h2>
<p>This is the playhtml starter. Edit the code on the left, watch the preview on the right. Hover the capabilities below to see which elements are collaborative.</p>
  
<ol class="capabilities">
<li onmouseenter="highlightElements('can-play')" onmouseleave="unhighlightElements('can-play')">can-play (custom capabilities)</li>
<li onmouseenter="highlightElements('can-move')" onmouseleave="unhighlightElements('can-move')">can-move</li>
<li onmouseenter="highlightElements('can-mirror')" onmouseleave="unhighlightElements('can-mirror')">can-mirror</li>
<li onmouseenter="highlightElements('can-toggle')" onmouseleave="unhighlightElements('can-toggle')">can-toggle</li>
<li onmouseenter="highlightElements('can-spin')" onmouseleave="unhighlightElements('can-spin')">can-spin</li>
preview↻
# Hello World!
Click to clone me!
CHANGE COLOR
## playhtml starter
This is the playhtml starter. Edit the code on the left, watch the preview on the right. Hover the capabilities below to see which elements are collaborative.
  1. can-play (custom capabilities)
  2. can-move
  3. can-mirror
  4. can-toggle
  5. can-spin
  6. can-grow
  7. can-duplicate
  8. can-hover


★
Here's a playhtml event. It triggers a shooting star for everyone. shooting star!
here's a custom guestbook made with can-mirror
say hi


here's a reaction button — everyone sees the count
react 0
</body>
</html>
```

--------------------------------

### Bundler Integration: Module Import with Options

Source: https://playhtml.fun/docs/getting-started

Import and initialize playhtml within your project when using a bundler. Ensure the `playhtml.init()` call runs after your interactive elements are mounted in the DOM.

```javascript
import { playhtml } from "playhtml";
playhtml.init({ cursors: { enabled: true } });
```

--------------------------------

### Getting User Count from Cursor Data

Source: https://playhtml.fun/docs/integrations/building-with-ai

Retrieve the total number of active users by checking the length of the allColors array in the cursor data.

```javascript
window.cursors.allColors.length
```

--------------------------------

### Filter array by time cutoff

Source: https://playhtml.fun/docs/data/data-essentials

Clean up arrays by removing old items based on a time cutoff. This example removes messages older than 24 hours.

```javascript
// Or time-bucket
setData((draft) => {
  const cutoff = Date.now() - 24 * 60 * 60 * 1000;
  draft.messages = draft.messages.filter((m) => m.timestamp > cutoff);
  draft.messages.push(newMessage);
});
```

--------------------------------

### Limit array size to last 100 items

Source: https://playhtml.fun/docs/data/data-essentials

Prevent unbounded array growth by limiting the number of items stored. This example keeps only the last 100 messages.

```javascript
// Keep last 100
setData((draft) => {
  draft.messages.push(newMessage);
  if (draft.messages.length > 100) {
    draft.messages.splice(0, draft.messages.length - 100);
  }
});
```

--------------------------------

### Debounce mousemove events

Source: https://playhtml.fun/docs/data/data-essentials

Use debouncing to limit the frequency of updates from high-frequency DOM events like mousemove. This example sets a 100ms delay before updating data.

```javascript
let pending;
element.addEventListener("mousemove", (e) => {
  clearTimeout(pending);
  pending = setTimeout(() => setData({ x: e.clientX, y: e.clientY }), 100);
});
```

--------------------------------

### Listening for Cursor Changes in Vanilla HTML

Source: https://playhtml.fun/docs/integrations/building-with-ai

Set up event listeners to react to changes in cursor data, specifically the allColors array, in vanilla JavaScript.

```javascript
window.cursors.on('allColors', callback)
```

--------------------------------

### Vanilla HTML Cursor Configuration for PlayHTMl

Source: https://playhtml.fun/docs/integrations/building-with-ai

Enable and configure cursors in PlayHTMl for vanilla JavaScript projects by passing options to playhtml.init().

```javascript
playhtml.init({ cursors: { enabled: true, room: "page" } })
```

--------------------------------

### React Provider with Init Options

Source: https://playhtml.fun/docs/reference/init-options

Integrates PlayHTML into a React application using the PlayProvider component. All initialization options are passed via the `initOptions` prop.

```jsx
import { PlayProvider } from "@playhtml/react";

<PlayProvider
  initOptions={{
    room: "my-room",
    cursors: { enabled: true },
    developmentMode: true,
  }}
>
  {/* your app */}
</PlayProvider>;
```

--------------------------------

### Dispatch Event with Payload (Vanilla HTML)

Source: https://playhtml.fun/docs/data/events

Initialize an event listener for 'nudge' that accepts a 'color' payload to change the background color. Dispatch the event with the payload to trigger the visual change.

```javascript
playhtml.init({
  events: {
    nudge: {
      type: "nudge",
      onEvent: ({ color }) => {
        document.body.animate(
          [{ backgroundColor: color }, { backgroundColor: "" }],
          { duration: 600 }
        );
      },
    },
  },
});

playhtml.dispatchPlayEvent({
  type: "nudge",
  eventPayload: { color: "#f7dc9c" },
});
```

--------------------------------

### Vanilla HTML: Module Import with Options

Source: https://playhtml.fun/docs/getting-started

Integrate PlayHTML using a module import when you need to pass options, such as enabling cursors. This method is suitable for projects without a build step, placing the script at the end of the body.

```html
<body>
  <button id="my-lamp" can-toggle>lamp</button>

  <script type="module">
    import { playhtml } from "https://unpkg.com/playhtml";
    playhtml.init({ cursors: { enabled: true } });
  </script>
</body>
```

--------------------------------

### Create Shared State Component with Dynamic Default Data

Source: https://playhtml.fun/docs/using-react

When default data depends on props, pass a callback function to `withSharedState` that returns the default data. This example shows a reaction counter button.

```jsx
export const ReactionView = withSharedState(
  ({ reaction: { count } }) => ({ defaultData: { count } }),
  ({ data, setData }, { reaction: { emoji } }) => (
    <button onClick={() => setData({ count: data.count + 1 }) }>
      {emoji} {data.count}
    </button>
  ),
);
```

--------------------------------

### Custom Guestbook with Mirror Capability

Source: https://playhtml.fun/docs/play

A custom guestbook implementation that utilizes the 'can-mirror' capability to synchronize messages across users.

```html
here's a custom guestbook made with can-mirror
say hi
```

--------------------------------

### React Component for Transformed Canvas Cursors

Source: https://playhtml.fun/docs/data/presence/cursors

Initialize PlayHTML cursors within a React application, specifying a container element for custom pan and zoom behavior. This setup ensures cursors are correctly positioned on a transformed canvas.

```jsx
<PlayProvider
  initOptions={{
    cursors: {
      enabled: true,
      container: ".content",
    },
  }}>
  <div className="content">
    {/* pan/zoom transform applied here via React state */}
    {words.map(w => <FridgeWord key={w.id} {...w} />)}
  </div>
</PlayProvider>
```

--------------------------------

### Event API from usePlayContext

Source: https://playhtml.fun/docs/reference/react-api

Illustrates how to destructure and use the event handling functions (register, remove, dispatch) from the Play HTML context.

```jsx
const {
  registerPlayEventListener,
  removePlayEventListener,
  dispatchPlayEvent,
} = usePlayContext();
```

--------------------------------

### Initializing PlayHTML with Cursor Configuration

Source: https://playhtml.fun/docs/data/presence/cursors

Configure cursor behavior during PlayHTML initialization. This is useful for pages that apply CSS transforms to a wrapper element, ensuring cursors remain correctly positioned for all users.

```APIDOC
## Initialize PlayHTML with Cursor Options

### Description
Enables and configures the cursor functionality within PlayHTML. Specifically useful when a container element has CSS transforms applied (like pan and zoom), this option ensures cursors are rendered in a consistent coordinate space across different user views.

### Method
`playhtml.init(options)`

### Parameters
#### Options Object
- **cursors** (object) - Optional - Configuration for cursor behavior.
  - **enabled** (boolean) - Required - Set to `true` to enable cursors.
  - **container** (string) - Optional - A CSS selector for the container element that has a CSS transform applied. If provided, PlayHTML will read the transform matrix from this element to correctly position cursors in a shared coordinate space.
```

--------------------------------

### Display User Count with Global Cursors API

Source: https://playhtml.fun/docs/data/presence/cursors

Implement a simple display for the number of online users by listening to the 'allColors' event from the global `window.cursors` object. The count updates automatically when users join or leave.

```html
<div id="user-count">👥 <span>0</span> online</div>

<script>
  const updateCount = () => {
    const count = window.cursors?.allColors?.length || 0;
    document.querySelector('#user-count span').textContent = count;
  };

  window.cursors?.on('allColors', updateCount);
  updateCount();
</script>
```

--------------------------------

### Using usePlayContext Hook

Source: https://playhtml.fun/docs/reference/react-api

Demonstrates accessing the Play HTML context using the usePlayContext hook. Shows how to retrieve the hasSynced state for conditional logic.

```jsx
const { hasSynced } = usePlayContext();
useEffect(() => {
  if (hasSynced) setData({ count: data.count + 1 });
}, [hasSynced]);
```

--------------------------------

### Specify a custom PartyKit host

Source: https://playhtml.fun/docs/reference/init-options

Pass your own PartyKit host to self-host the syncing server for greater control, custom server-side logic, or data-residency.

```javascript
playhtml.init({
  host: "mypartykit.user.partykit.dev",
});
```

--------------------------------

### Mirror Input and Button

Source: https://playhtml.fun/docs/play

An input field and a button, both with the 'can-mirror' capability. Changes in the input field are reflected in the button's text, and vice-versa, demonstrating real-time synchronization.

```html
<input id="colorBox" can-mirror/>
```

```html
<button id="btn" can-mirror>CHANGE COLOR</button>
```

--------------------------------

### Enable development mode

Source: https://playhtml.fun/docs/reference/init-options

Enable the in-page devtools panel for debugging, which includes an element inspector, live data tree, and connection status.

```javascript
playhtml.init({ developmentMode: true });
```

--------------------------------

### Cursor Presence Subscription

Source: https://playhtml.fun/docs/data/presence

Specific instructions for subscribing to cursor movement updates.

```APIDOC
## Cursor Presence Subscription

### Description
Subscribes to real-time cursor movement updates. Cursor positions are updated frequently (~60fps).

### Method

#### `onPresenceChange(channel: "cursor", callback: (presences: Map<string, Presence>) => void): () => void`
Subscribes to changes in the "cursor" channel.

- **channel** ("cursor") - Must be the string "cursor".
- **callback** (function) - Receives a Map of presences, each containing cursor data.
- **Returns**: A function to unsubscribe from cursor updates.

### Note
For pixel-accurate cursor rendering, consider using the dedicated cursor system directly.
```

--------------------------------

### Admin Cleanup (Bulk)

Source: https://playhtml.fun/docs/data/data-essentials

This endpoint is used for sites that did not clean up at runtime and need to sweep orphans. It allows for a bulk removal of orphaned entries.

```APIDOC
## POST /parties/main/{roomId}/admin/cleanup-orphans

### Description
Allows for bulk cleanup of orphaned data by removing entries that were not cleaned up at runtime. It is recommended to perform a dry run first.

### Method
POST

### Endpoint
/parties/main/{roomId}/admin/cleanup-orphans

### Parameters
#### Path Parameters
- **roomId** (string) - Required - The ID of the room for which to perform the cleanup.

#### Request Body
- **tag** (string) - Required - The tag associated with the entries to be cleaned.
- **activeIds** (array of strings) - Required - A list of active IDs to consider during cleanup. This list should be derived from your own data store.
- **dryRun** (boolean) - Optional - If true, performs a dry run without actually removing entries. Defaults to false.

### Request Example
```json
{
  "tag": "can-move",
  "activeIds": ["id1", "id2", "id3"],
  "dryRun": false
}
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **tag** (string) - The tag associated with the cleanup operation.
- **total** (integer) - The total number of entries considered.
- **active** (integer) - The number of active entries found.
- **removed** (integer) - The number of orphaned entries removed.
- **message** (string) - A message describing the result of the cleanup operation.

#### Response Example
```json
{
  "ok": true,
  "tag": "can-move",
  "total": 5000,
  "active": 100,
  "removed": 4900,
  "message": "Removed 4900 orphaned entries"
}
```
```

--------------------------------

### Subscribing to Cursor Presence Changes

Source: https://playhtml.fun/docs/data/presence

Listen for real-time cursor movement updates, which are exposed as a special 'cursor' presence channel. Updates occur at approximately 60fps.

```javascript
const unsub = playhtml.presence.onPresenceChange("cursor", (presences) => {
  renderCursorPositions(presences);
});
```

--------------------------------

### React Cursor Configuration for PlayHTMl

Source: https://playhtml.fun/docs/integrations/building-with-ai

Configure cursors for PlayHTMl in React applications by passing initialization options to the PlayProvider component.

```javascript
<PlayProvider initOptions={{ cursors: { enabled: true, room: "page" } }}>
```

--------------------------------

### Data Updates in PlayHTMl (Simple and Array)

Source: https://playhtml.fun/docs/integrations/building-with-ai

Demonstrates how to perform simple data updates and array modifications using the setData function in PlayHTMl.

```javascript
setData({ count: data.count + 1 })
```

```javascript
setData((draft) => { draft.items.push(item) })
```

--------------------------------

### Local state then commit for mousemove

Source: https://playhtml.fun/docs/data/data-essentials

Manage ephemeral state locally and sync only on commit events like mouseup. This approach prevents excessive syncing during continuous interactions.

```javascript
let localX = data.x;
element.addEventListener("mousemove", (e) => {
  localX = e.clientX;
  element.style.left = `${localX}px`;
});
element.addEventListener("mouseup", () => {
  setData({ x: localX });
});
```

--------------------------------

### Custom Channels

Source: https://playhtml.fun/docs/data/presence

Information on how to define and use custom presence channels.

```APIDOC
## Custom Channels

### Description
Allows users to define and share custom data channels as part of their presence. Channel names should not collide with system fields (`playerIdentity`, `cursor`, `isMe`).

### Setting and Clearing Channels

#### `setMyPresence(channel: string, value: any | null)`
Sets or clears a custom channel for the current user.

- **channel** (string) - The name of the custom channel (e.g., "status", "focus").
- **value** (any | null) - The data for the channel (e.g., `{ text: "typing" }`) or `null` to clear.

### Overwriting Semantics
Calling `setMyPresence` for a channel completely overwrites the existing value for that channel. There are no partial or merge updates for custom channels.
```

--------------------------------

### Configure Other Cursor Options

Source: https://playhtml.fun/docs/data/presence/cursors

Configure various other cursor options including custom player identity, proximity detection, visibility thresholds, and chat enablement.

```javascript
cursors: {
  enabled: true,

  // Custom player identity
  playerIdentity: {
    name: "Alice",
    playerStyle: {
      colorPalette: ["#3b82f6", "#8b5cf6", "#ec4899"]
    }
  },

  // Proximity detection
  proximityThreshold: 150,  // pixels
  onProximityEntered: (playerIdentity, positions, angle) => {
    console.log("User nearby!", playerIdentity.name);
  },
  onProximityLeft: (connectionId) => {
    console.log("User left proximity");
  },

  // Visibility threshold (hide distant cursors)
  visibilityThreshold: 1000,  // pixels

  // Enable chat
  enableChat: true,

  // Custom cursor rendering
  onCustomCursorRender: (connectionId, element) => {
    // Return custom element or null for default
    return null;
  }
}
```

--------------------------------

### Registering a Single PlayHTML Element

Source: https://playhtml.fun/docs/advanced/dynamic-elements

Use `playhtml.setupPlayElement` to register a single DOM node after it has been added to the DOM. This function is idempotent. You can pass `{ ignoreIfAlreadySetup: true }` to prevent re-registration if the node has already been set up.

```javascript
playhtml.setupPlayElement(element, {
  ignoreIfAlreadySetup: true
});
```

--------------------------------

### Listen for Cursor State Changes

Source: https://playhtml.fun/docs/data/presence/cursors

Subscribe to events on the global `window.cursors` object to be notified when cursor states change. This includes updates to all user colors, your color, and your name. You can also unsubscribe from these events.

```javascript
// Listen for color changes
window.cursors.on('allColors', (colors) => {
  console.log(`${colors.length} users online`);
});

window.cursors.on('color', (myColor) => {
  console.log(`My color changed to ${myColor}`);
});

window.cursors.on('name', (myName) => {
  console.log(`My name changed to ${myName}`);
});

// Stop listening
window.cursors.off('allColors', callback);
```

--------------------------------

### Presence API Methods

Source: https://playhtml.fun/docs/data/presence

This section details the core methods for managing and retrieving presence information.

```APIDOC
## Presence API Methods

### Description
Provides methods to set, get, and subscribe to presence information for connected users.

### Methods

#### `setMyPresence(channel: string, value: any | null)`
Sets or clears a custom presence channel for the current user.

- **channel** (string) - The name of the custom channel.
- **value** (any | null) - The data to set for the channel, or `null` to clear it.

#### `getPresences(): Map<string, Presence>`
Retrieves presence information for all currently connected users.

- **Returns**: A Map where keys are user IDs and values are `Presence` objects.

#### `onPresenceChange(channel: string, callback: (presences: Map<string, Presence>) => void): () => void`
Subscribes to changes in a specific presence channel. The callback is invoked only when the specified channel changes for any user.

- **channel** (string) - The name of the channel to subscribe to.
- **callback** (function) - The function to call when the channel changes. It receives a Map of presences.
- **Returns**: A function to unsubscribe from the channel changes.

#### `getMyIdentity(): PlayerIdentity`
Retrieves the identity information for the current user.

- **Returns**: An object containing the user's name, colors, and public key.

### Presence Object Structure

- **isMe** (boolean) - True if this presence belongs to the current user.
- **playerIdentity** (PlayerIdentity) - The identity of the user.
- **cursor** ({ x: number, y: number, pointer: string } | null) - The user's cursor position and type, or null if not available.
- **[customChannelName]** (any) - Data for any custom channels set by the user.
```

--------------------------------

### Workspace Rooms for Custom Groupings

Source: https://playhtml.fun/docs/data/presence/cursors

Create custom cursor groupings based on application logic, such as workspace IDs extracted from the URL. This allows for granular control over presence visibility.

```javascript
playhtml.init({
  cursors: {
    enabled: true,
    room: ({ domain, pathname }) => {
      // Extract workspace ID from URL
      const match = pathname.match(///workspace/(\w+)/);
      if (match) {
        return `${domain}-workspace-${match[1]}`;
      }
      return `${domain}${pathname}`;
    }
  }
});
```

--------------------------------

### Use localStorage for per-user preferences

Source: https://playhtml.fun/docs/data/data-essentials

Store personal preferences like reaction status or settings in `localStorage` instead of syncing them. This ensures data is user-specific and not shared.

```javascript
const reactedKey = `reacted-${elementId}`;
const hasReacted = Boolean(localStorage.getItem(reactedKey));

onClick: (_e, { data, setData }) => {
  if (hasReacted) {
    setData({ count: data.count - 1 });
    localStorage.removeItem(reactedKey);
  } else {
    setData({ count: data.count + 1 });
    localStorage.setItem(reactedKey, "true");
  }
};
```

--------------------------------

### Cleanup Orphans Helper Script

Source: https://playhtml.fun/docs/data/data-essentials

Execute this script from the terminal to perform administrative cleanup. It's recommended to perform a dry run first by setting DRY_RUN=true.

```bash
export ADMIN_TOKEN=your_token_here

# Dry run first to see what would be removed
DRY_RUN=true bun scripts/cleanup-orphans.ts "playhtml.fun-fridge" "can-move" "id1" "id2" "id3"

# Actually perform the cleanup
bun scripts/cleanup-orphans.ts "playhtml.fun-fridge" "can-move" "id1" "id2" "id3"
```

--------------------------------

### Enable Cursors in React

Source: https://playhtml.fun/docs/data/presence/cursors

Initialize Playhtml with cursor tracking enabled using the PlayProvider component in a React application.

```javascript
import { PlayProvider } from "@playhtml/react";

<PlayProvider
  initOptions={{
    cursors: {
      enabled: true,
    }
  }}
>
  {/* your app */}
</PlayProvider>
```

--------------------------------

### Using CanMoveElement with Bounds

Source: https://playhtml.fun/docs/reference/react-api

Demonstrates how to use the CanMoveElement component to make elements draggable within a specified container. Shows default and customized bounds behavior.

```jsx
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" boundsMinVisible={0.5} boundsMinVisiblePx={0}>
    <div id="magnet-b">🥐</div>
  </CanMoveElement>
</div>;
```

--------------------------------

### Reading All User Presences

Source: https://playhtml.fun/docs/data/presence

Retrieve a map of all connected users' presence data, including system fields and custom channels. Each entry indicates if it's the local user.

```javascript
const presences = playhtml.presence.getPresences();
for (const [id, p] of presences) {
  p.isMe;            // boolean
  p.playerIdentity;  // name, colors, publicKey
  p.cursor;          // { x, y, pointer } | null
  p.status;          // your custom channel (if set)
}
```

--------------------------------

### Admin Cleanup Endpoint

Source: https://playhtml.fun/docs/data/data-essentials

Use this POST endpoint to clean up orphaned data for a specific room. Always dry-run first and derive activeIds from your data store.

```http
POST /parties/main/{roomId}/admin/cleanup-orphans
```

```json
{
  "tag": "can-move",
  "activeIds": ["id1", "id2", "id3"],
  "dryRun": false
}
```

```json
{
  "ok": true,
  "tag": "can-move",
  "total": 5000,
  "active": 100,
  "removed": 4900,
  "message": "Removed 4900 orphaned entries"
}
```

--------------------------------

### Replacement Form for Data Updates

Source: https://playhtml.fun/docs/data/data-essentials

Use the replacement form to overwrite the entire data snapshot. This is safer for simple values like booleans where the last write should always win.

```javascript
setData({ ...data, on: !data.on });
```

--------------------------------

### Customizing can-move Bounds Visibility (Vanilla)

Source: https://playhtml.fun/docs/capabilities

Control the minimum visible portion of a dragged element using `can-move-bounds-min-visible` (fraction) and `can-move-bounds-min-visible-px` (pixels).

```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>
```

--------------------------------

### Basic can-move Usage in React

Source: https://playhtml.fun/docs/capabilities

Use the `CanMoveElement` component from `@playhtml/react` to enable drag-and-drop functionality. Specify the container using the `bounds` prop.

```jsx
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>
```

--------------------------------

### Vanilla HTML can-grow

Source: https://playhtml.fun/docs/capabilities

Use the 'can-grow' attribute on an image element for click-to-scale-up and alt-click-to-scale-down functionality in vanilla HTML.

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

--------------------------------

### Mirroring :hover State with CSS

Source: https://playhtml.fun/docs/advanced/mirror-playground

This snippet demonstrates how to use the `data-playhtml-hover` attribute to synchronize the hover state of an element across clients. CSS can then target this attribute to apply styles, such as changing the background color.

```html
<style>
  #pg-mirror-hover[data-playhtml-hover] {
    background: #4caf50;
    color: white;
  }
</style>

<div can-mirror id="pg-mirror-hover">Hover me</div>
```

--------------------------------

### Set a custom room name

Source: https://playhtml.fun/docs/reference/init-options

Override the default room derived from the URL to decouple state from the URL. Useful for site-wide features like guestbooks.

```javascript
playhtml.init({ room: "global-guestbook" });
```
Tokens:
Raw