unicornstudio-react

A React component for embedding Unicorn.Studio interactive scenes in your applications. Compatible with both React (Vite) and Next.js frameworks.

⚠️ Important: This package is a community-created wrapper component and is not officially affiliated with Unicorn.Studio. It depends on Unicorn.Studio's proprietary script and services.

Features

🚀 Easy Integration - Simple React component for Next.js projects
🎨 Full TypeScript Support - Complete type definitions included
⚡ Performance Optimized - Lazy loading and efficient resource management
📱 Responsive - Works seamlessly across devices
🎮 Interactive - Support for mouse/touch interactions
🔧 Flexible - Extensive customization options
🧹 Clean Architecture - Proper cleanup and memory management
🛡️ Error Handling - Comprehensive error states and fallbacks

Installation

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

Usage

This package supports both React (Vite/CRA) and Next.js environments with optimized imports:

For React (Vite, Create React App, etc.)

Use the default import for standard React applications:

import UnicornScene from "unicornstudio-react";

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

For Next.js

Use the Next.js-optimized version:

import UnicornScene from "unicornstudio-react/next";

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

Note: Both the React and Next.js builds load the bundled Unicorn Studio SDK by default. Pass sdkUrl if you need to override that with a custom hosted SDK URL.

With Custom JSON File

React (Vite/CRA):

import UnicornScene from "unicornstudio-react";

export default function MyComponent() {
  return (
    <UnicornScene
      jsonFilePath="/path/to/your/scene.json"
      width="100%"
      height="400px"
      scale={0.8}
      dpi={2}
    />
  );
}

SDK Loading

By default, this package loads the bundled Unicorn Studio SDK files that ship with the package.

Use sdkUrl only when you need to override that behavior and load the SDK from a custom hosted URL:

<UnicornScene
  projectId="YOUR_PROJECT_EMBED_ID"
  sdkUrl="https://your-custom-cdn.com/unicornStudio.umd.js"
  width={800}
  height={600}
/>

If you are maintaining this package itself and need to refresh the bundled SDK files, place the upstream files in vendor/unicornstudio/ and run:

npm run sync-sdk

Next.js:

import UnicornScene from "unicornstudio-react/next";

export default function MyComponent() {
  return (
    <UnicornScene
      jsonFilePath="/path/to/your/scene.json"
      width="100%"
      height="400px"
      scale={0.8}
      dpi={2}
    />
  );
}

Advanced Configuration

Both React and Next.js versions support the same props:

// For React: import UnicornScene from "unicornstudio-react";
// For Next.js: import UnicornScene from "unicornstudio-react/next";
import UnicornScene from "unicornstudio-react";

export default function MyComponent() {
  const handleLoad = () => {
    console.log("Scene loaded successfully!");
  };

  const handleError = (error: Error) => {
    console.error("Scene loading failed:", error);
  };

  return (
    <UnicornScene
      projectId="YOUR_PROJECT_EMBED_ID"
      width="100vw"
      height="100vh"
      scale={1}
      dpi={1.5}
      fps={60}
      altText="Interactive 3D scene"
      ariaLabel="Animated background scene"
      className="my-custom-class"
      lazyLoad={true}
      production={true}
      onLoad={handleLoad}
      onError={handleError}
    />
  );
}

Accessing the Scene Instance

Use the sceneRef prop when you want access to the underlying Unicorn Studio scene object after it initializes.

import { useRef } from "react";
import UnicornScene, { type UnicornStudioScene } from "unicornstudio-react";

export default function MyComponent() {
  const sceneRef = useRef<UnicornStudioScene | null>(null);

  const pauseScene = () => {
    if (sceneRef.current) {
      sceneRef.current.paused = true;
    }
  };

  const resizeScene = () => {
    sceneRef.current?.resize?.();
  };

  return (
    <>
      <UnicornScene
        projectId="YOUR_PROJECT_EMBED_ID"
        width={800}
        height={600}
        sceneRef={sceneRef}
      />

      <button onClick={pauseScene}>Pause</button>
      <button onClick={resizeScene}>Resize</button>
    </>
  );
}

The sceneRef value is assigned once the scene finishes loading and is cleared automatically if the scene is destroyed or re-initialized.

Placeholder Support

The component now supports flexible placeholder options that can be displayed while loading, on error, or when WebGL is not supported.

Image Placeholder

<UnicornScene
  projectId="YOUR_PROJECT_ID"
  placeholder="/path/to/placeholder.jpg"
  width={800}
  height={600}
/>

CSS/Tailwind Placeholder

<UnicornScene
  projectId="YOUR_PROJECT_ID"
  placeholderClassName="bg-gradient-to-r from-blue-500 to-purple-600 animate-pulse"
  width="100%"
  height="400px"
/>

Custom React Component Placeholder

<UnicornScene
  projectId="YOUR_PROJECT_ID"
  placeholder={
    <div className="flex items-center justify-center h-full bg-gray-100">
      <div className="text-center">
        <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-gray-900 mx-auto"></div>
        <p className="mt-4 text-gray-600">Loading 3D Scene...</p>
      </div>
    </div>
  }
  width={600}
  height={400}
/>

Placeholder Behavior Options

showPlaceholderWhileLoading: Shows placeholder during scene initialization (default: true)
showPlaceholderOnError: Shows placeholder when scene fails to load (default: true)
The placeholder automatically shows when WebGL is not supported

Props

Prop	Type	Default	Description
`projectId`	`string`	-	The Unicorn Studio project embed ID (required if not using `jsonFilePath`)
`jsonFilePath`	`string`	-	Path to a self-hosted JSON file (required if not using `projectId`)
`sdkUrl`	`string`	-	Optional custom SDK URL; otherwise the bundled SDK is used
`width`	`number \| string`	`"100%"`	Width of the scene container
`height`	`number \| string`	`"100%"`	Height of the scene container
`scale`	`number`	`1`	Rendering scale (0.25-1, lower values improve performance)
`dpi`	`number`	`1.5`	Pixel ratio for rendering quality
`fps`	`number`	`60`	Frames per second (0-120)
`altText`	`string`	`"Scene"`	Alternative text for accessibility
`ariaLabel`	`string`	-	ARIA label for the scene
`className`	`string`	`""`	Additional CSS classes
`lazyLoad`	`boolean`	`true`	Load scene only when scrolled into view
`production`	`boolean`	`true`	Use production mode when initializing the scene
`paused`	`boolean`	`false`	Pause or resume the scene animation
`placeholder`	`string \| ReactNode`	-	Placeholder content (image URL or React component)
`placeholderClassName`	`string`	-	CSS classes for placeholder div (when using CSS placeholder)
`showPlaceholderOnError`	`boolean`	`true`	Show placeholder when scene fails to load
`showPlaceholderWhileLoading`	`boolean`	`true`	Show placeholder while scene is loading
`onLoad`	`() => void`	-	Callback when scene loads successfully
`onError`	`(error: Error) => void`	-	Callback when scene fails to load
`sceneRef`	`Ref<UnicornStudioScene \| null>`	-	Ref that receives the initialized Unicorn Studio scene instance

Styling

The component uses inline styles for maximum compatibility. You can customize the appearance by:

Using the className prop to add your own CSS classes
Wrapping the component in a styled container
Using CSS variables for dynamic dimensions:

<div style={{ "--unicorn-width": "100%", "--unicorn-height": "500px" }}>
  <UnicornScene projectId="YOUR_PROJECT_ID" />
</div>

Getting Your Project ID

Create your scene at Unicorn Studio
Click on "Embed" in the export options
Copy the project ID from the embed code

Framework Compatibility

React Version (Default)

✅ Vite - Optimized for modern React development
✅ Create React App (CRA) - Classic React setup
✅ Webpack - Custom React builds
✅ Parcel - Zero-configuration bundler
✅ Rollup - ES modules bundler

Next.js Version (`/next`)

✅ Next.js 13+ - App Router and Pages Router
✅ Next.js 14+ - Latest features and optimizations
✅ Vercel deployment - Optimized hosting
✅ Static exports - JAMstack compatibility

Dependencies & Requirements

Unicorn.Studio SDK Dependency

This component depends on Unicorn.Studio's proprietary SDK files, which:

✅ Are bundled with this package and loaded locally by default
✅ Can still be overridden with the sdkUrl prop
🏢 Are owned by Unicorn.Studio (UNCRN LLC)
⚖️ Are subject to Unicorn.Studio's Terms of Service

Custom Script URL (Advanced)

<UnicornScene
  projectId="YOUR_PROJECT_EMBED_ID"
  sdkUrl="https://your-custom-cdn.com/unicornStudio.umd.js"
  width={800}
  height={600}
/>

Browser Support

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)
Mobile browsers with WebGL support

Versioning Strategy

This package's version follows Unicorn.Studio's script version (e.g., v1.4.26) to ensure compatibility. Version format:

1.4.26 - Matches Unicorn.Studio script v1.4.26
Patch versions (e.g., 1.4.26-1) may be added for component-specific fixes

Performance Tips

Use appropriate scale values - Lower values (0.5-0.8) can significantly improve performance on lower-end devices
Enable lazy loading - Scenes will only initialize when visible
Optimize your scenes - Keep texture sizes reasonable in Unicorn Studio
Set appropriate DPI - Use lower DPI values for better performance

Troubleshooting

Scene not loading

Verify your project ID is correct
Check network requests for the Unicorn Studio script
Ensure you're not mixing projectId and jsonFilePath

Performance issues

Reduce the scale prop value
Lower the dpi setting
Decrease fps for less demanding animations

TypeScript errors

Ensure you have the latest version installed
Check that your tsconfig includes the necessary DOM types

Development & Architecture

This component is based on the official Unicorn.Studio React example with the following improvements:

Enhancements Over Official Example

Modern React Patterns
- Custom hooks for script loading and scene management
- Proper TypeScript integration with full type definitions
- Shared SDK loader across React and Next.js
Better Architecture
- Separation of concerns (hooks, types, constants)
- Proper cleanup and memory management
- Error boundaries and comprehensive error handling
Enhanced Developer Experience
- Complete TypeScript support
- Inline styles for zero-config styling
- Extensive prop customization options
- npm package distribution
Production Ready
- Proper build pipeline with tsup
- CommonJS and ESM support
- Automated script deduplication
- Comprehensive documentation

Legal & Licensing

This Package (MIT License)

This React component wrapper is released under the MIT License - see the LICENSE file for details.

Unicorn.Studio Dependencies

Unicorn.Studio SDK files: Proprietary software owned by UNCRN LLC
Terms: Subject to Unicorn.Studio's Terms of Service
Licensing: Commercial use governed by Unicorn.Studio's licensing terms

Disclaimer

This package is a community-created wrapper and is not officially affiliated with Unicorn.Studio or UNCRN LLC. The authors of this package:

Distribute Unicorn.Studio SDK files only as part of this wrapper package
Are not responsible for Unicorn.Studio's service availability or performance
Recommend users comply with Unicorn.Studio's Terms of Service
Provide this wrapper "as-is" without warranty

For official support or licensing questions regarding Unicorn.Studio, contact Unicorn.Studio directly.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

git clone https://github.com/diegopeixoto/unicornstudio-react.git
cd unicornstudio-react
npm install
npm run dev

Links

Unicorn Studio - Official website
Unicorn Studio Documentation - Official docs
GitHub Repository - This package
npm Package - npm registry

Author: Diego Peixoto
License: MIT (for this wrapper component only)
Not affiliated with: Unicorn.Studio or UNCRN LLC

Name		Name	Last commit message	Last commit date
Latest commit History 125 Commits
.claude		.claude
.github/workflows		.github/workflows
scripts		scripts
src		src
vendor/unicornstudio		vendor/unicornstudio
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.mcp.json		.mcp.json
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
sonar-project.properties		sonar-project.properties
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

unicornstudio-react

Features

Installation

Usage

For React (Vite, Create React App, etc.)

For Next.js

With Custom JSON File

SDK Loading

Advanced Configuration

Accessing the Scene Instance

Placeholder Support

Image Placeholder

CSS/Tailwind Placeholder

Custom React Component Placeholder

Placeholder Behavior Options

Props

Styling

Getting Your Project ID

Framework Compatibility

React Version (Default)

Next.js Version (/next)

Dependencies & Requirements

Unicorn.Studio SDK Dependency

Custom Script URL (Advanced)

Browser Support

Versioning Strategy

Performance Tips

Troubleshooting

Scene not loading

Performance issues

TypeScript errors

Development & Architecture

Enhancements Over Official Example

Legal & Licensing

This Package (MIT License)

Unicorn.Studio Dependencies

Disclaimer

Contributing

Development Setup

Links

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 16

Uh oh!

Contributors

Uh oh!

Languages

Next.js Version (`/next`)