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:

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

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

Getting Your Project ID

1. Create your scene at Unicorn Studio
2. Click on "Embed" in the export options
3. 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

1. Use appropriate scale values - Lower values (0.5-0.8) can significantly improve performance on lower-end devices
2. Enable lazy loading - Scenes will only initialize when visible
3. Optimize your scenes - Keep texture sizes reasonable in Unicorn Studio
4. 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

1. 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

2. Better Architecture

   • Separation of concerns (hooks, types, constants)
   • Proper cleanup and memory management
   • Error boundaries and comprehensive error handling

3. Enhanced Developer Experience

   • Complete TypeScript support
   • Inline styles for zero-config styling
   • Extensive prop customization options
   • npm package distribution

4. 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