clay.js
  1. ClayJS
  2. Guide
  3. Quick start

Quick start

Download an HTML file that edits itself and saves back to disk, see how it works, then try live sync.

In a few minutes, you will have an HTML file that edits itself in the browser and saves every change back into the file on your disk.

Install HTML Clay#

Get HTML Clay and install it on your computer. A browser cannot write to a file on disk, and HTML Clay is the small free desktop app that does.

Download a self-saving HTML file#

Download my-list.htmlclay, or copy it from the block below and save it as my-list.htmlclay. Save the file anywhere in your home folder (Downloads is fine) and double-click it; HTML Clay opens it in your browser, ready to edit.

HTML
<!DOCTYPE html>
<html lang="en" autosave opens-in="edit">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>My list</title>
<style>
  body {
    font: 17px/1.6 system-ui, -apple-system, "Segoe UI", sans-serif;
    color: #2B2723; background: #F1EFEA;
    max-width: 30em; margin: 0 auto; padding: 7vh 22px 12vh;
  }
  h1 { font-size: 30px; line-height: 1.2; margin: 0 0 4px; }
  p.sub { color: #57514A; margin: 0 0 26px; }
  ul { list-style: none; margin: 0; padding: 0; }
  li { display: flex; align-items: center; gap: 12px; padding: 13px 2px; border-bottom: 1px solid #DDD8CE; }
  input[type=checkbox] { width: 19px; height: 19px; flex: none; accent-color: #3E6B52; cursor: pointer; }
  input[type=checkbox]:checked + span { color: #57514A; text-decoration: line-through; }
  :focus-visible { outline: 2px solid #3E6B52; outline-offset: 3px; }
</style>
</head>
<body>

<h1 editmode:contenteditable inert-contenteditable="plaintext-only">My list</h1>
<p class="sub">What I need to get done.</p>

<ul>
  <li><input type="checkbox" persist aria-labelledby="t1"> <span id="t1" editmode:contenteditable inert-contenteditable="plaintext-only">Buy oat milk</span></li>
  <li><input type="checkbox" persist aria-labelledby="t2"> <span id="t2" editmode:contenteditable inert-contenteditable="plaintext-only">Book the dentist</span></li>
  <li><input type="checkbox" persist aria-labelledby="t3"> <span id="t3" editmode:contenteditable inert-contenteditable="plaintext-only">Water the fig tree</span></li>
</ul>

<script>
  document.addEventListener("keydown", (event) => {
    if (event.key !== "Enter" || event.isComposing) return;
    if (!event.target.matches?.('[contenteditable="plaintext-only"]')) return;
    event.preventDefault();
    event.target.blur();
  });
</script>
<script src="https://clayjs.com/v1/clay.js?plugins=sync,undo,indicator,menu&exclude=richclay"></script>
</body>
</html>

The file is plain HTML under the .htmlclay extension, so renaming it to .html opens it in any browser.

How the file saves itself#

Five parts of the markup make the page editable and self-saving:

  • <script src="https://clayjs.com/v1/clay.js?plugins=sync,undo,indicator,menu&exclude=richclay"></script> loads ClayJS at the end of <body>.
  • autosave on <html> saves the whole document a moment after your edits settle.
  • opens-in="edit" on <html> starts the page in edit mode for anyone who can edit. It grants no permission, so a person who cannot edit the file gets the page in view mode.
  • editmode:contenteditable inert-contenteditable="plaintext-only" makes text typable in place, as plain text. The file keeps the inert spelling, and ClayJS turns it on only in edit mode, so a reader gets ordinary text.
  • persist writes a checkbox’s checked state into the HTML as an attribute.

Every save writes the whole document back into the same file on disk.

The script’s URL picks what else the page has:

  • sync keeps every open tab of the file up to date.
  • undo adds whole-page undo on Cmd+Z. While the cursor is in a text field or a task name, Cmd+Z stays with the browser.
  • indicator draws a small chip in the bottom right that shows the save status.
  • menu draws an Edit switch in the top right for anyone who can edit.
  • exclude=richclay leaves out the rich text editor, which removes the editable attribute. This page does not use it.

The short inline script makes Enter finish the edit. Without it, Enter adds a line break to the task name, and the next save writes that line break into the file.

For formatted text, drop &exclude=richclay from the script and use editable in place of the two plain text attributes. See richclay.

Edit the page and check the file#

The page opens in edit mode. Click any task name and type a new task name, then tick the second checkbox (“Book the dentist”). Wait two seconds for autosave to finish, then open my-list.htmlclay in your text editor. Your new words are right there in the file, and the checkbox you ticked now has a checked attribute. ClayJS keeps the file’s own spelling and writes a new empty attribute bare, so that saved line of HTML looks like this:

HTML
<li><input type="checkbox" persist aria-labelledby="t2" checked> <span id="t2" editmode:contenteditable inert-contenteditable="plaintext-only">Book the dentist</span></li>

Uncheck the box, wait two seconds, and look at the file again to see the checked attribute removed.

The Edit switch turns editing off in this tab. The next time you open the file, it starts in edit mode again.

Live sync is already on#

The script loads the sync plugin, so live sync needs no setup. Edit the task text in your text editor and save the file, and the open page updates in place without a reload. Duplicate the browser tab so two tabs show the file at once, and an edit in one tab appears in the other right away. This works between open tabs on one computer.

Next steps#

Part of the ClayJS complete guideDownload the whole guide as Markdown