HyperclayJS API Reference

// Show a success message
toast('Changes saved!', 'success');

// Show an error message
toast('Something went wrong', 'error');

// Success is the default type
toast('Uploaded successfully');

// Basic usage with async/await
const name = await ask('What is your name?');
console.log('Hello, ' + name);

// With a default value
const title = await ask('Enter title:', null, 'Untitled');

// With callback
ask('Enter your email:', (email) => {
  console.log('Email:', email);
});

// With extra content
ask('Confirm action:', null, '', '<p class="warning">This cannot be undone</p>');

// Basic usage with async/await
try {
  await consent('Delete this item?');
  deleteItem();
} catch (e) {
  // User cancelled
}

// With callback
consent('Are you sure?', () => {
  performAction();
});

// With extra content
consent('Publish changes?', null, '<p>This will be visible to all users.</p>');

// Simple message
await tell('Welcome!');

// With additional content
await tell(
  'About This App',
  'This is a collaborative editing platform.',
  'Changes are saved automatically.',
  'Press CMD+S to save manually.'
);

// Informational popup
tell('Tip', 'You can drag and drop items to reorder them.');

// Show embed code
snippet('Embed Code', '<iframe src="https://example.com"></iframe>');

// With a warning message
snippet(
  'API Key',
  'sk-1234567890abcdef',
  'Keep this key secret. Do not share it publicly.'
);

// Show configuration
const config = JSON.stringify({ theme: 'dark', lang: 'en' }, null, 2);
snippet('Your Settings', config);

// Basic custom modal
themodal.html = '<h2>Custom Title</h2><p>Your content here</p>';
themodal.yes = 'Confirm';
themodal.no = 'Cancel';

themodal.onYes(() => {
  console.log('User confirmed');
});

themodal.onNo(() => {
  console.log('User cancelled');
});

themodal.open();

// Modal with form validation
themodal.html = '<input class="micromodal__input" type="email" required>';
themodal.yes = 'Submit';

themodal.onYes(() => {
  const email = document.querySelector('.micromodal__input').value;
  if (!email.includes('@')) {
    toast('Invalid email', 'error');
    return false; // Prevent modal from closing
  }
  processEmail(email);
});

themodal.open();

// Toggle visibility on all cards
All('.card').classList.toggle('hidden');

// Get values from all inputs
const values = All('input').map(el => el.value);

// Event delegation for dynamic content
All(document).onclick('.dynamic-btn', function() {
  console.log('Button clicked:', this.dataset.id);
});

// Chained operations
All('.notification')
  .classList.add('fade-out')
  .style.opacity = '0';

// Iterate with for...of
for (const el of All('.item')) {
  el.textContent = 'Updated';
}

// External stylesheet
insertStyles('/styles/theme.css');

// Load from CDN
insertStyles('https://cdn.example.com/lib.css');

// Inline CSS with a name (for deduplication)
insertStyles('my-theme', `
  .dark-mode { background: #1a1a1a; color: #fff; }
`);

// Safe to call multiple times - old duplicates are removed
insertStyles('/styles/theme.css'); // Replaces previous

// From a form element
const form = document.querySelector('form');
const data = getDataFromForm(form);
// { username: 'john', email: 'john@example.com' }

// From any container
const container = document.querySelector('.filter-panel');
const filters = getDataFromForm(container);

// Checkbox handling
// <input type="checkbox" name="tags" value="js" checked>
// <input type="checkbox" name="tags" value="css" checked>
// Result: { tags: ['js', 'css'] }

// Use with fetch
const formData = getDataFromForm(form);
fetch('/api/submit', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(formData)
});

// Initialize app when DOM is ready
onDomReady(() => {
  initializeApp();
  setupEventListeners();
});

// Safe to call after page load - runs immediately
onDomReady(() => {
  console.log('This runs right away if DOM is already loaded');
});

// Wait for all images and resources to load
onLoad(() => {
  initializeImageGallery();
  calculateLayoutDimensions();
});

// Difference from onDomReady:
// - onDomReady: DOM structure ready, images may still be loading
// - onLoad: Everything loaded including images, fonts, iframes

// Find nearest element with [project] or .project
const projectEl = this.nearest.project;

// Get/set values (smart: uses .value for form elements, attribute otherwise)
const projectName = this.val.project;
this.val.project = "New Name";

// Get/set innerText
const label = this.text.title;
this.text.title = "Updated Title";

// Execute code from an attribute
// If <div sync_out="savePage()"> exists nearby, this runs savePage()
this.exec.sync_out();

// Cycle through elements
// Replaces current element with next element having [variant] attribute
this.cycle(1, 'variant');   // forward
this.cycle(-1, 'variant');  // backward

// Cycle through attribute values
// Sets theme to next value found on any [theme] element
this.cycleAttr(1, 'theme');

// Cycle with different lookup attribute
// Sets color based on values from [option:color] elements
this.cycleAttr(1, 'color', 'option:color');

slugify('Hello World');
// 'hello-world'

slugify('Café & Restaurant');
// 'cafe-restaurant'

slugify('  Multiple   Spaces  ');
// 'multiple-spaces'

slugify('Ñoño with Accénts');
// 'nono-with-accents'

// Use for URLs
const title = 'My Blog Post Title!';
const url = `/posts/${slugify(title)}`;
// '/posts/my-blog-post-title'

// Copy a URL
copyToClipboard('https://example.com/share/123');

// Copy with user feedback
copyToClipboard(embedCode);
toast('Copied to clipboard!');

// Copy from an element
const code = document.querySelector('pre').textContent;
copyToClipboard(code);

// URL: https://example.com/page?name=john&page=2&active=true

query.name;    // 'john'
query.page;    // '2'
query.active;  // 'true'

// Check if parameter exists
if (query.debug) {
  enableDebugMode();
}

// Use with defaults
const page = query.page || '1';
const sort = query.sort || 'date';

// Destructure parameters
const { name, page, sort = 'date' } = query;

// Throttle scroll handler to once per 100ms
const handleScroll = throttle(() => {
  updateScrollPosition();
}, 100);

window.addEventListener('scroll', handleScroll);

// Throttle resize handler
const handleResize = throttle(() => {
  recalculateLayout();
}, 200);

window.addEventListener('resize', handleResize);

// Don't execute immediately on first call
const lazyUpdate = throttle(updateUI, 500, false);

// Debounce search input
const searchInput = document.querySelector('#search');
const handleSearch = debounce((query) => {
  fetchSearchResults(query);
}, 300);

searchInput.addEventListener('input', (e) => {
  handleSearch(e.target.value);
});

// Debounce window resize
const handleResize = debounce(() => {
  recalculateLayout();
}, 250);

window.addEventListener('resize', handleResize);

// Auto-save after user stops typing
const autoSave = debounce(() => {
  saveDraft();
}, 1000);

// Cache-bust a stylesheet link
const link = document.querySelector('link[rel="stylesheet"]');
cacheBust(link);
// href="/styles.css" becomes "/styles.css?v=1702847291234"

// Cache-bust an image
const img = document.querySelector('img');
cacheBust(img);
// src="/photo.jpg?v=123" becomes "/photo.jpg?v=1702847291234"

// Use with onaftersave to reload Tailwind CSS after save
// <link href="/tailwindcss/mysite.css" onaftersave="cacheBust(this)">

// Get a cookie value
const userId = cookie.get('userId');

// Get JSON cookie (auto-parsed)
const preferences = cookie.get('userPrefs');
// { theme: 'dark', lang: 'en' }

// Check if cookie exists
if (cookie.get('authToken')) {
  showLoggedInUI();
}

// Remove a cookie
cookie.remove('sessionId');

// Clear authentication
cookie.remove('authToken');
cookie.remove('userId');

// Watch for any DOM changes (debounced)
const unsubscribe = Mutation.onAnyChange({ debounce: 200 }, (changes) => {
  changes.forEach(change => {
    console.log(change.type, change.element);
  });
});

// Watch for new elements matching a selector
Mutation.onAddElement({ selectorFilter: '.card' }, (changes) => {
  changes.forEach(({ element }) => {
    initializeCard(element);
  });
});

// Watch for attribute changes
Mutation.onAttribute({ debounce: 100 }, (changes) => {
  changes.forEach(({ element, attribute, oldValue, newValue }) => {
    console.log(`${attribute} changed from ${oldValue} to ${newValue}`);
  });
});

// Simple debounced callback without change details
Mutation.onAnyChange({ debounce: 500, omitChangeDetails: true }, () => {
  console.log('DOM changed');
});

// Stop observing
unsubscribe();

// Find the nearest button
const btn = nearest(clickedElement, 'button');

// Find nearest input field from a label
const input = nearest(label, 'input');

// Find nearest and get its value
const value = nearest(el, '[data-value]', el => el.dataset.value);

// Find related UI elements
const card = nearest(deleteBtn, '.card');
card.remove();

// Find next input in reading order
const nextInput = nearest(currentInput, 'input:not(:disabled)');
nextInput?.focus();

// Handle form submission
document.querySelector('form').onsubmit = (e) => {
  sendMessage(e, 'Message sent!');
};

// Event outside a form (sends behavior data only)
document.querySelector('#contact-btn').onclick = (e) => {
  sendMessage(e, 'Contact request sent!');
};

// Send custom data object
sendMessage({
  name: 'John',
  email: 'john@example.com'
}, 'Contact form submitted');

// With async/await
try {
  const result = await sendMessage(formEvent);
  redirectToThankYou();
} catch (error) {
  console.error('Failed:', error);
}

// Handle file input
document.querySelector('input[type="file"]').onchange = (e) => {
  uploadFile(e, (response) => {
    console.log('Uploaded to:', response.urls);
  });
};

// Upload a File object directly
const file = new File(['content'], 'test.txt', { type: 'text/plain' });
uploadFile(file);

// With extra metadata
uploadFile(event, null, {
  folder: 'images',
  public: true
});

// Progress is shown automatically via toasts:
// "10% uploaded" → "50% uploaded" → "80% uploaded" → "Uploaded! URL copied"

// From form submission
document.querySelector('#create-file-form').onsubmit = (e) => {
  createFile(e);
};

// From object
createFile({
  fileName: 'styles.css',
  fileBody: '.container { max-width: 1200px; }'
});

// From arguments
createFile('config.json', JSON.stringify({ theme: 'dark' }));

// Content type auto-detection:
// - HTML content → .html
// - CSS content → .css
// - JavaScript → .js
// - Valid JSON → .json
// - Unknown → .txt

// With custom progress UI
uploadFileBasic(fileInput.files[0], {
  onProgress: (percent) => {
    progressBar.style.width = percent + '%';
    progressText.textContent = percent + '%';
  },
  onComplete: (response) => {
    progressBar.classList.add('complete');
    showSuccessMessage(response.urls[0]);
  },
  onError: (error) => {
    progressBar.classList.add('error');
    showErrorMessage(error.message);
  }
});

// Minimal usage
uploadFileBasic(event, {
  onComplete: (res) => console.log('Done:', res.urls)
});

// With async/await
try {
  const result = await uploadFileBasic(file, {
    onProgress: p => console.log(p + '%')
  });
  console.log('Uploaded:', result);
} catch (err) {
  console.error('Failed:', err);
}

// Check if in edit mode
if (hyperclay.isEditMode) {
  // Show edit UI
}

// Check if user owns the resource
if (hyperclay.isOwner) {
  // Show owner-only controls
}

// Toggle edit mode (reloads page with ?editmode=true/false)
hyperclay.toggleEditMode();

// Manual save
hyperclay.savePage();

// Save with callback
hyperclay.savePage(({msg, msgType}) => {
  if (msgType === 'error') {
    console.error('Save failed:', msg);
  }
});

// Register before-save hook
hyperclay.beforeSave((clone) => {
  // Modify the snapshot clone before saving
  clone.querySelectorAll('.temp').forEach(el => el.remove());
});

// Replace page with template
hyperclay.replacePageWith('/templates/blog.html');