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

Click "Copy to Framer" in the export window and paste in your Framer project. That's it!

Or: 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 notes: - Your 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.

Webflow

  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.5.3/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 JSON 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

Wix

  1. In your Site Settings menu, click Custom Code in the Advanced section
  2. Click + Add Custom Code
  3. Paste in the following script: 
    <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.5.3/dist/unicornStudio.umd.js",i.onload=function(){window.UnicornStudio.isInitialized||(UnicornStudio.init(),window.UnicornStudio.isInitialized=!0)},(document.head || document.body).appendChild(i)}}();</script>
  4. Name it "Unicorn Studio SDK" (or whatever you want)
  5. Select All pages under "Add Code to Pages"
  6. Choose Head under "Place Code in"
  7. Click Apply
  8. In the Wix Editor, add an HTML Embed element where you want your scene to appear
  9. Click on the HTML Embed element and select Enter Code
  10. Paste your scene HTML (see "Example implementation" below)
  11. Click Update and Save

Figma Sites

  • Copy the component from the export window or paste this code into a new Make component.
  • Paste your Project ID/JSON into the field
  • That's it!
  • Your scene won't render in edit mode, preview or publish to see it action.

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-fixed Makes the scene behaved like a fixed element
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 JS 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();

See the documentation on GitHub

React / Next.js

Unofficial but totally awesome React/Next wrapper available here. 

npm install unicornstudio-react
# or
yarn add unicornstudio-react
# or
pnpm add unicornstudio-react

import UnicornScene from "unicornstudio-react";

export default function MyComponent() {
  return (
    <UnicornScene projectId="YOUR_PROJECT_EMBED_ID" width={800} height={600} />
  );
}

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