@rare-lab/react

React component for embedding Rare.lab visual effects into any React application. Drop a single component into your app and get production-ready WebGL shader effects — no build configuration, no Three.js dependency, no runtime overhead.

Install

npm install @rare-lab/react

Requirements: React 18 or later.

Quick Start

import { RareScene } from '@rare-lab/react'

export default function Hero() {
  return (
    <div style={{ width: '100%', height: '100vh' }}>
      <RareScene sceneId="your-scene-id" />
    </div>
  )
}

The sceneId is the ID you get after publishing a scene in the Rare.lab editor.

Usage with Next.js

<RareScene> includes 'use client' — it works in both App Router and Pages Router without extra configuration.

// app/page.tsx
import { RareScene } from '@rare-lab/react'

export default function Page() {
  return (
    <section className="hero">
      <RareScene
        sceneId="your-scene-id"
        width="100%"
        height="100vh"
        hoverReactive
      />
    </section>
  )
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | sceneId | string | (required) | Published scene ID from the Rare.lab editor | | width | number \| string | '100%' | Container width. Numbers are treated as pixels. | | height | number \| string | '100%' | Container height. Numbers are treated as pixels. | | className | string | — | CSS class name on the container div | | style | CSSProperties | — | Additional inline styles on the container div | | poster | string | — | Image URL shown while the scene loads | | scrollDriven | boolean | false | Enable scroll-driven animation | | hoverReactive | boolean | false | Enable mouse/hover reactivity | | state | string | — | Set the interaction state machine state | | ariaLabel | string | 'Animated visual effect' | Accessible label for screen readers | | cdnBase | string | Rare.lab CDN | Override the CDN base URL (advanced) | | onLoad | (detail: { sceneId: string }) => void | — | Called when the scene finishes loading | | onError | (error: { code: string; message: string; sceneId?: string }) => void | — | Called on any runtime error |

Interactivity

Scenes built with interaction nodes in the Rare.lab editor respond to user input automatically. Enable the relevant prop to activate each interaction type:

// Mouse-reactive background
<RareScene sceneId="..." hoverReactive />

// Scroll-driven animation
<RareScene sceneId="..." scrollDriven />

// Programmatic state control
<RareScene sceneId="..." state="active" />

Callbacks

<RareScene
  sceneId="your-scene-id"
  onLoad={({ sceneId }) => {
    console.log(`Scene ${sceneId} loaded`)
  }}
  onError={({ code, message }) => {
    console.error(`Scene error [${code}]: ${message}`)
  }}
/>

Accessibility

The component renders with role="img" and a configurable aria-label. It respects prefers-reduced-motion — when the user's OS is set to reduce motion, the scene displays a static poster image instead of animating.

How It Works

The component loads the Rare.lab runtime (rare.min.js) from the CDN once, then renders your published scene as a <rare-scene> web component inside a container div. The runtime is shared across all <RareScene> instances on the page — multiple scenes don't load the script twice.

Scenes that use 3D mesh nodes automatically lazy-load the 3D renderer chunk. Scenes that only use 2D effects never download it.

License

MIT