Get Started with Hyperclay

Build your first self-modifying HTML app in minutes.

What You’ll Build

In this guide, you’ll create a simple task list that:

Saves automatically when you make changes
Has different views for visitors and admins
Persists data without any database setup
Works as a single, portable HTML file

1. Create Your App

Go to hyperclay.com
Choose a name for your HTML App (e.g., “my-tasks”)
Click “Create Site”

2. Add Your First HTML

Click “Edit Code” in your app’s menu
Replace the default HTML with this starter template:


<!DOCTYPE html>
<html lang="en">
<head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Todo App</title>
 <link rel="stylesheet" href="https://hyperclay.com/css/tailwind-base.css">
 <script src="https://hyperclay.com/js/hyperclay-starter-kit.js" type="module"></script>
 <script src="https://hyperclay.com/js/vendor/tailwind-play.js"></script>
</head>
<body class="font-sans max-w-2xl mx-auto mt-10 px-5">
 <h1 edit-mode-contenteditable class="text-3xl font-bold mb-6">Todo App</h1>
 
 <!-- Tasks -->
 <div id="tasks" class="space-y-3">
   <!-- Hidden template for new tasks -->
   <div class="task hidden p-4 bg-gray-100 rounded-lg flex items-center gap-3">
     <input type="checkbox" persist class="w-4 h-4">
     <span edit-mode-contenteditable class="flex-1">New Task</span>
     <button option:editmode="true" class="delete px-3 py-1 bg-red-500 text-white rounded hover:bg-red-600">Delete</button>
   </div>
   
   <div class="task p-4 bg-gray-100 rounded-lg flex items-center gap-3">
     <input type="checkbox" persist class="w-4 h-4">
     <span edit-mode-contenteditable class="flex-1">Learn Hyperclay</span>
     <button option:editmode="true" class="delete px-3 py-1 bg-red-500 text-white rounded hover:bg-red-600">Delete</button>
   </div>
 </div>
 
 <!-- This only shows for admins -->
 <button id="add-task" option:editmode="true" class="mt-4 px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600">Add Task</button>
 
 <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js"></script>
 <script>
 $(function() {
   const $tasks = $('#tasks');
   const $template = $tasks.find('.task.hidden');
   
   // Add Task
   $('#add-task').on('click', function() {
     const $clone = $template.clone(true).removeClass('hidden');
     $tasks.append($clone);
   });
   
   // Delete Task
   $tasks.on('click', '.delete', function() {
     $(this).closest('.task').remove();
   });
 });
 </script>
</body>
</html>

Click “Save” or press Cmd/Ctrl+S

3. Understanding the Magic

Let’s break down what makes this Hyperclay app special:

The Hyperclay Starter Kit

❗️ You don’t need to use the starter kit, it just makes things easier. You can also, often with just a few lines of vanilla JS, implement what it does yourself.


<script src="https://hyperclay.com/js/hyperclay-starter-kit.js" type="module"></script>

This single line enables:

Auto-save: Changes to the DOM are automatically saved
Edit/View modes: Detects custom attributes, adds admin-only functionality based on them
DOM persistence: Form values and content changes can easily be persisted to the DOM

Key Attributes

option:editmode="true" - Shows elements only in edit mode:


<div option:editmode="true">Only admins see this</div>

persist - Makes form values save to the DOM:


<input type="checkbox" persist>

edit-mode-contenteditable - Makes text editable for admins only:


<span edit-mode-contenteditable>Click to edit (admins only)</span>

The Save Lifecycle

You make a change (check a box, edit text, add an element)
Hyperclay detects the change via mutation observers
Before saving, admin-only elements are stripped out
The clean HTML is saved to the server
When loading, admin elements are re-injected if you’re the owner

4. Try Your Live App

Visit https://your-app-name.hyperclay.com
As the owner, you’ll see:
- Admin controls panel
- Editable task text
- Delete buttons
- Everything saves automatically!
Try these actions:
- Check some boxes - they stay checked after refresh
- Click on task text to edit it inline
- Add new tasks with the button
- Toggle edit mode to see the visitor view
Open in an incognito window to see the clean, read-only visitor view

5. What’s Next?

Quick Experiments

Try adding these features to understand Hyperclay better:

Element that cleans itself up before saving:


<div class="temp" onbeforesave="this.remove()">
  This element disappears on save
</div>

Sortable tasks:


<div id="tasks" sortable="tasks">
  <!-- Tasks can now be dragged to reorder -->
</div>