- ClayJS
- Guide
- Introduction
Introduction
What ClayJS is, how to read this guide, and the example apps it quotes.
ClayJS is a script to give HTML files super powers.
It lets the file edit itself and save changes back into itself. With the sync plugin, it also merges edits from other tabs, other people, and agents. The file stays plain HTML.
ClayJS is for people and AI agents to collaborate: a tracker, a board, a notes page, a dashboard a team edits. Saving needs a host that accepts saves: e.g. HTML Clay, Hyperclay Local, hyperclay.com.
Skip ClayJS if your file is static and not meant to be edited. Add ClayJS on the day someone needs to edit the HTML file and collaborate on it.
How to read this guide#
Open the problem list, pick the problems you are solving, and read those pages. Everything else can wait. The complete reference stays available as one Markdown file for the details.
Building with an AI agent? Give it the problem list, so it reads only the pages the task needs. The whole guide is also one Markdown file, for when it needs the details.
Every behavior stated here was read from ClayJS 1.17.0 source or executed. The four example files below are complete, tested apps that this guide quotes. A test suite boots each one in jsdom with the real loader and checks what it saves, how it merges a peer’s edit, and what a viewer receives. Open any of them and view source, or download one and open it in HTML Clay to edit it:
| File | What it shows |
|---|---|
examples/skeleton.html | The smallest correct app: a sortable reading list with persisted checkboxes, a derived summary, a tab-local filter, sync and undo. Start every new file from it. |
examples/kanban.html | Columns and cards with cross-column drag, a card detail view that is the card itself, checklists, an activity log, a filter, undo. |
examples/writer.html | A block document: rich text blocks, headings, callouts, to-do blocks, dividers, images with upload, a gutter with drag handle and block menu, a slash menu, an outline and a word count. |
examples/finance.html | A budget built on sap.js: categories with budgets, transactions, computed totals saved into the file, search, CSV import and export. |
Code in this guide assumes the loader URL https://clayjs.com/v1/. Add ClayJS to a page covers versions. This guide is also served as plain Markdown at clayjs.com/guide.md for agents, and its ideas are drawn as diagrams in the visual guide.