unicornstudio-react

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 with enhanced performance:

import UnicornScene from "unicornstudio-react/next";

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

Note: The Next.js version uses Next.js Script and Image components for better performance and optimization. The React version uses standard <script> and <img> elements for broader compatibility.

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}
    />
  );
}

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)
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 CDN
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 Script Dependency

This component depends on Unicorn.Studio's proprietary script (unicornStudio.umd.js) which:

• ✅ Is automatically loaded from Unicorn.Studio's official CDN
• ❌ Is NOT bundled or stored in this package
• 🏢 Is owned and hosted by Unicorn.Studio (UNCRN LLC)
• ⚖️ Is subject to Unicorn.Studio's Terms of Service

Custom Script URL (Advanced)

// ⚠️ Use custom script URL (may violate Unicorn.Studio TOS)
// Only use if you have explicit permission from Unicorn.Studio
const constants = {
  UNICORN_STUDIO_CDN_URL: "https://your-custom-cdn.com/unicornStudio.umd.js",
};

Warning: Using a custom script URL may violate Unicorn.Studio's Terms of Service. Consult their legal terms before implementing.

React/Next.js Example usage:

<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
  • Next.js Script component for optimized loading

• 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 Script: 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:

• Do not store, distribute, or modify Unicorn.Studio's proprietary scripts
• 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