Documentation

Everything you need to integrate beautifi into your project.

01 Quick Start

CDN (Simplest)

<script 
  src="https://unpkg.com/@beautifi/plugin" 
  data-api-key="YOUR_API_KEY"
></script>

All images matching img or [data-beautifi] will be animated automatically.

NPM / ES Modules

npm install @beautifi/plugin

import { beautifi } from '@beautifi/plugin';

beautifi.init({
  apiKey: 'YOUR_API_KEY',
  intensity: 'subtle',
  type: 'auto',
  mode: 'auto'  // CSS animation + AI video
});

02 Opt-In Mode

For pages with many images, use opt-in mode to only animate specific images:

<!-- Enable opt-in mode via script tag -->
<script 
  src="https://unpkg.com/@beautifi/plugin" 
  data-api-key="YOUR_API_KEY"
  data-opt-in="true"
></script>

<!-- Mark images to animate -->
<img src="hero.jpg" data-beautifi-animate />
<img src="product.jpg" data-beautifi-animate />

Programmatic Opt-In

beautifi.init({
  apiKey: 'YOUR_API_KEY',
  optIn: true  // Only animate [data-beautifi] images
});

03 Configuration

Option	Type	Default	Description
apiKey	string	—	Your API key (required)
selector	string	img, [data-beautifi]	CSS selector for target images
intensity	string	subtle	subtle \| medium \| strong
type	string	auto	auto \| breathing \| parallax \| sway
mode	string	auto	auto (CSS + video) \| css \| video
optIn	boolean	false	Only animate [data-beautifi-animate] images
loop	boolean	true	Loop animation continuously
debug	boolean	false	Enable console logging

04 Events

Animation Events

// CSS animation lifecycle
document.addEventListener('beautifi:animationStart', (e) => {
  console.log('Animation started:', e.detail.imageId);
});

document.addEventListener('beautifi:animationComplete', (e) => {
  console.log('Animation finished:', e.detail.imageId);
});

document.addEventListener('beautifi:animationError', (e) => {
  console.error('Error:', e.detail.error);
});

Video Events

// AI video generation lifecycle
document.addEventListener('beautifi:videoStart', (e) => {
  console.log('Video generation started:', e.detail.imageId);
});

document.addEventListener('beautifi:videoReady', (e) => {
  console.log('Video ready:', e.detail.videoUrl);
});

document.addEventListener('beautifi:videoError', (e) => {
  console.log('Video failed, CSS continues:', e.detail.imageId);
});

05 Quick Test

Test beautifi on any page — paste this one-liner in your browser's developer console:

(()=>{const s=document.createElement('script');s.src='https://cdn.jsdelivr.net/npm/@beautifi/plugin/dist/beautifi.min.js';s.onload=()=>{(window.beautifi.beautifi||window.beautifi.default).init({apiKey:'demo',endpoint:'https://api.beautifi.uk/animate',debug:true});console.log('beautifAI loaded!')};document.head.appendChild(s)})();

Full API Reference

Explore all methods, types, and advanced configuration options.

View API Reference →