- ClayJS
- Guide
- Introduction
Introduction
What ClayJS is, how to read this guide, and the example apps it quotes.
This is the complete reference for building malleable documents with ClayJS: one HTML file that is the whole app, edits itself in place, saves itself back to its host, and merges edits from other tabs, other people and agents. Read it top to bottom once. After that, A document, line by line, Structuring an app and Pre-ship checklist are the parts to return to.
Building with an AI agent? Copy or download the whole guide as one Markdown file and give it to your agent. It is this guide, every chapter, kept current.
It is written for a developer or an LLM building full apps with inline editing and inline controls: kanban boards with card detail, block writers, finance trackers, CRMs, flashcards, trackers. It covers the CMS plugin only in passing (cms: content-managed pages), because an app whose product is editing should not route editing through a form sidebar.
Every behavior stated here was read from ClayJS 1.8.2 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.