Unicorn Wrapper

"use client"

import { UnicornWrapper } from "@/components/ui/unicorn-wrapper"

export function UnicornWrapperDemo() {
  return (
    <div className="flex size-[400px] items-center justify-center overflow-hidden rounded-2xl">
      <UnicornWrapper
        className="h-full w-full"
        projectId="OpSYWgbtD97AYWlhMu2W"
        production
      />
    </div>
  )
}

Installation

pnpmnpmyarnbun
pnpm dlx pitsi@latest add unicorn-wrapper
Copy

Usage

Copyimport { UnicornWrapper } from "@/components/ui/unicorn-wrapper"

Copy<UnicornWrapper className="h-[400px] w-full" projectId="your-project-id" />

About Unicorn Studio

Unicorn Studio is a tool for creating interactive 3D and motion graphics that can be embedded in React applications. The UnicornWrapper component provides an optimized way to integrate Unicorn Studio projects into your pitsi/ui applications.

Features

• Performance Optimized: Uses Intersection Observer to only render projects when visible in viewport
• Error Handling: Gracefully handles errors and prevents crashes
• Lazy Loading: Projects load only when they enter the viewport (with 50px margin)
• Production Ready: Automatically enables production mode for better performance
• Automatic Cleanup: Properly cleans up observers on unmount
• Ref Support: Fully supports React refs for advanced use cases

Examples

Basic Project

Copy<UnicornWrapper projectId="abc123xyz" className="h-[500px] w-full" />

Responsive Project

Copy<div className="container mx-auto">
  <UnicornWrapper projectId="def456uvw" className="aspect-video w-full" />
</div>

Project with Custom Styling

Copy<UnicornWrapper
  projectId="ghi789rst"
  className="h-96 rounded-lg border shadow-lg"
/>

Props

The component accepts all props from UnicornSceneProps from the unicornstudio-react package, plus:

For the complete list of available props, see the Unicorn Studio React documentation.

How It Works

The wrapper enhances the base UnicornScene component with:

1. Intersection Observer: Monitors when the component enters/exits the viewport
2. Conditional Rendering: Only renders the project when visible (with 50px margin)
3. Error Boundary: Catches errors and unmounts the component to prevent crashes
4. Ref Forwarding: Supports both callback and object refs

This approach significantly improves performance when you have multiple projects on a page or projects that are initially offscreen.

Getting Your Project ID

To use this component, you'll need:

1. Create a project at unicorn.studio
2. Get your project ID from the Unicorn Studio dashboard
3. Use the project ID in the component props

Notes

• The component requires unicornstudio-react to be installed
• Projects only load when they're within 50px of entering the viewport
• Production mode is enabled by default for better performance
• If a project errors, it will automatically unmount to prevent app crashes
• The wrapper has a 10% intersection threshold for triggering visibility