{"id":18072,"library":"unicornstudio-react","title":"Unicorn.Studio React Component","description":"The `unicornstudio-react` package provides a community-created React component for embedding interactive 3D scenes designed with Unicorn.Studio into web applications. Currently at version `2.1.4-1`, this library sees frequent updates, often involving bumps to the underlying Unicorn.Studio SDK and fixes for compatibility issues in modern React and Next.js environments. Key differentiators include full TypeScript support, an optimized import path specifically for Next.js applications (leveraging Next.js `Script` and `Image` components), performance optimizations like lazy loading, responsive design, and comprehensive error handling. It allows embedding scenes using either a project ID from Unicorn.Studio's cloud service or a local JSON file. It's important to note that this package is not officially affiliated with Unicorn.Studio and relies on their proprietary script and services.","status":"active","version":"2.1.4-1","language":"javascript","source_language":"en","source_url":"https://github.com/diegopeixoto/unicornstudio-react","tags":["javascript","react","nextjs","next.js","vite","unicorn-studio","unicornstudio","animation","webgl","typescript"],"install":[{"cmd":"npm install unicornstudio-react","lang":"bash","label":"npm"},{"cmd":"yarn add unicornstudio-react","lang":"bash","label":"yarn"},{"cmd":"pnpm add unicornstudio-react","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React component functionality.","package":"react","optional":false},{"reason":"Peer dependency for React component functionality.","package":"react-dom","optional":false}],"imports":[{"note":"This is the default export path for standard React environments (e.g., Vite, Create React App). It uses standard HTML `<script>` and `<img>` tags for integration.","wrong":"const UnicornScene = require('unicornstudio-react');","symbol":"UnicornScene","correct":"import UnicornScene from 'unicornstudio-react';"},{"note":"For Next.js applications, use this specific import path. It leverages Next.js `Script` and `Image` components for enhanced performance, optimization, and SSR-safety.","wrong":"import UnicornScene from 'unicornstudio-react';","symbol":"UnicornScene (Next.js optimized)","correct":"import UnicornScene from 'unicornstudio-react/next';"},{"note":"The package ships with full TypeScript types. Import `UnicornSceneProps` for type-checking the component's properties, useful for advanced configurations or custom wrappers.","symbol":"UnicornSceneProps (Type)","correct":"import type { UnicornSceneProps } from 'unicornstudio-react';"}],"quickstart":{"code":"import { useState } from 'react';\nimport UnicornScene from 'unicornstudio-react/next';\n\nexport default function InteractiveScenePage() {\n  const [isSceneLoaded, setIsSceneLoaded] = useState(false);\n  const [error, setError] = useState<Error | null>(null);\n\n  const handleLoad = () => {\n    console.log('Unicorn.Studio scene loaded successfully!');\n    setIsSceneLoaded(true);\n  };\n\n  const handleError = (err: Error) => {\n    console.error('Failed to load Unicorn.Studio scene:', err);\n    setError(err);\n  };\n\n  // Replace 'YOUR_PROJECT_EMBED_ID' with your actual project ID from Unicorn.Studio\n  // or use jsonFilePath=\"/path/to/your/scene.json\"\n  const projectId = process.env.NEXT_PUBLIC_UNICORN_STUDIO_PROJECT_ID ?? 'YOUR_PROJECT_EMBED_ID';\n\n  return (\n    <div style={{ width: '100vw', height: '100vh', display: 'flex', justifyContent: 'center', alignItems: 'center', background: '#f0f0f0' }}>\n      {!isSceneLoaded && !error && <p>Loading interactive scene...</p>}\n      {error && <p style={{ color: 'red' }}>Error loading scene: {error.message}</p>}\n      <UnicornScene\n        projectId={projectId}\n        width=\"100%\"\n        height=\"100%\"\n        scale={0.8}\n        dpi={2}\n        lazyLoad={true}\n        altText=\"An interactive 3D scene from Unicorn.Studio\"\n        onLoad={handleLoad}\n        onError={handleError}\n        style={{ border: '1px solid #ccc', borderRadius: '8px' }}\n      />\n    </div>\n  );\n}","lang":"typescript","description":"This quickstart demonstrates embedding a Unicorn.Studio interactive scene using the Next.js optimized component, including loading and error handling. It fetches a project ID from environment variables and sets various display properties."},"warnings":[{"fix":"Understand the external dependencies; ensure Unicorn.Studio services are operational and your project ID or JSON file path is correct. Check Unicorn.Studio's official documentation for service status.","message":"This package is a community-created wrapper and is not officially affiliated with Unicorn.Studio. Its operation depends on Unicorn.Studio's proprietary script and services, which are external to this package's control.","severity":"gotcha","affected_versions":"*"},{"fix":"Always review the Unicorn.Studio SDK changelog and `unicornstudio-react` release notes before upgrading major versions of the SDK. Test thoroughly after any updates.","message":"SDK version bumps can introduce breaking changes in the underlying Unicorn.Studio runtime. For instance, the transition to SDK v2.1.0 included a breaking change for flattened scenes if not updated.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade to `unicornstudio-react@2.1.4-1` or higher. Always use the Next.js-optimized import path: `import UnicornScene from 'unicornstudio-react/next';` to benefit from specific optimizations and bug fixes.","message":"Prior to version `2.1.4-1`, users in Next.js App Router environments, especially with React Strict Mode enabled, might experience issues such as duplicate canvas rendering or multiple script initializations. This was due to specific handling of script loading and component mounting.","severity":"gotcha","affected_versions":"<2.1.4-1"},{"fix":"For all Next.js projects, consistently use `import UnicornScene from 'unicornstudio-react/next';` to ensure optimal performance and compatibility.","message":"Using the default import `import UnicornScene from 'unicornstudio-react';` in a Next.js project will bypass the performance optimizations and specialized handling provided by the Next.js-optimized path. This can lead to less efficient script loading and image handling, impacting Lighthouse scores and overall performance.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Update to `unicornstudio-react@2.1.4-1` or newer. Ensure React Strict Mode is compatible or consider adjusting component keys if custom rendering logic is involved.","cause":"React Strict Mode causing re-renders that lead to duplicate canvas elements, often seen in Next.js environments with older versions of the component.","error":"Warning: Encountered two children with the same key, `__reactFiber$ID`..."},{"fix":"Verify that your `projectId` is correctly copied from Unicorn.Studio or that `jsonFilePath` points to an accessible JSON file. Check the browser console for network errors, JavaScript errors, or CSP violations. Ensure `https://cdn.jsdelivr.net` and `https://assets.unicorn.studio` are allowed in your CSP.","cause":"Incorrect `projectId` or `jsonFilePath`, network issues preventing the external Unicorn.Studio script from loading, or content security policy (CSP) blocking external scripts from Unicorn.Studio's CDN.","error":"Unicorn.Studio scene does not load, or a blank canvas is displayed in the browser."},{"fix":"Check for typos in `import UnicornScene from 'unicornstudio-react/next';`. Ensure `npm install unicornstudio-react` or `yarn add unicornstudio-react` was run successfully. If using an older bundler, ensure it supports the `exports` field in `package.json`.","cause":"Typo in the import path, or the `unicornstudio-react` package is not correctly installed or its `exports` map is not being properly resolved by your bundler.","error":"Module not found: Can't resolve 'unicornstudio-react/next'"},{"fix":"Ensure external script loading is not blocked by a Content Security Policy (CSP). Check network requests in developer tools to confirm the script (`unicornStudio.umd.js`) is loading. The component handles script loading automatically, but external factors can interfere. Consider using the `onLoad` prop to ensure readiness if manually interacting with the SDK or deferring related logic.","cause":"The Unicorn.Studio external script failed to load, was blocked, or took too long to load, and the component attempted to initialize before the global `UnicornStudio` object was available.","error":"ReferenceError: UnicornStudio is not defined (or similar error related to the global UnicornStudio object)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}