Skip to content

Embed Guide

Embedding is easy. Unicorn.studio uses a small (38kb gzipped) JavaScript library to execute your scenes with several implementation options. See the library on GitHub.

iFrame is not recommended for production sites

Framer Component

  1. Copy this component link: https://framer.com/m/UnicornStudioEmbed-wWy9.js
  2. Paste into your Framer project
  3. Paste your scene's Project ID into the first field
  4. Done!

Additional details:

  • You scene won't render in edit mode, preview or publish to see it action.
  • If your scene isn't updating, it could be the Framer cache. See more below.
  • If you have the Legend plan, you can paste your exported code into "Project JSON". This will make it load faster.
  • If you need to update your library version, right click the component and select "Unlink". You can see the library link inside the code. Update the version in the link to match the latest version.

Webflow Integration

  1. In Site Settings > Custom Code, add to footer: 

    <script type="text/javascript">!function(){if(!window.UnicornStudio){window.UnicornStudio={isInitialized:!1};var i=document.createElement("script");i.src="https://cdn.jsdelivr.net/gh/hiunicornstudio/unicornstudio.js@v1.4.19/dist/unicornStudio.umd.js",i.onload=function(){window.UnicornStudio.isInitialized||(UnicornStudio.init(),window.UnicornStudio.isInitialized=!0)},(document.head || document.body).appendChild(i)}}();</script>

  2. Choose the element you want to embed your scene in and click on the "settings" tab.

  3. Add a new "Custom Attribute". For name put data-us-project and for value add your project ID.
  4. You may add additional attributes to customize your scene using the settings defined below.

The container div you add data-us-project to must have a defined width and height.

Using code export

You can also use the data-us-project-src attribute to point to a hosted project JSON file. This will make it load faster.

  • Rename your code JSON to [your-file-name].json.txt
  • Upload it to your assets library
  • Use the menu to copy link and paste it as the value for data-us-project-src

SDK parameters

The SDK allows native integration with coded sites or Webflow. Configure using data-us-[param] attributes:

Parameter Description
data-us-project Points to your scene project id
data-us-project-src Path to hosted project JSON
data-us-scale Canvas rendering scale (0.25-1)
data-us-dpi Scene resolution (default: 1.5)
data-us-lazyload Defers resource creation until viewport entry
data-us-production Enables CDN serving
data-us-fps Sets render loop FPS
data-us-disablemobile Disables mobile mouse/scroll interactions
data-us-alttext SEO alt text
data-us-arialabel Accessibility label

Do not use both data-us-project and data-us-project-src. You must choose one or the other.

Example implementation: 

<div
data-us-project="YOUR_PROJECT_EMBED_ID"
data-us-scale="1"
data-us-dpi="1.5"
data-us-lazyload="true"
data-us-production="true"
data-us-alttext="Welcome to Unicorn Studio"
data-us-arialabel="This is a canvas scene"
></div>

Native Code Implementation

For modern web apps: 

// Import
import as UnicornStudio from './path/to/unicornStudio.umd.js'
// Component mount
UnicornStudio.init().then(scenes => {
// Scenes are ready
}).catch((err) => {
console.error(err);
});
// Component unmount
UnicornStudio.destroy();

React/Next.js example here.

Advanced Topics

Caching Behavior

Use the update query parameter to bypass caching:

<div data-us-project="JoBbhn1dDuRwdTcqZFPc?update=1.0.1"></div>

Production Mode

Enable production mode for optimal performance: - Use data-us-production="true" in HTML - Add ?production=true to project ID in Framer - Enable "production mode" when publishing

Note: Updates take 1-2 minutes to propagate through the CDN.

Next: Performance Guide