Convert Figma logo to code with AI

splinetool logoreact-spline

React component for Spline scenes.

1,176
58
1,176
30

Top Related Projects

🇨🇭 A React renderer for Three.js

101,622

JavaScript 3D Library.

Babylon.js is a powerful, beautiful, simple, and open game and rendering engine packed into a friendly JavaScript framework.

9,523

JavaScript game engine built on WebGL, WebGPU, WebXR and glTF

43,739

The HTML5 Creation Engine: Create beautiful digital content with the fastest, most flexible 2D WebGL renderer.

Quick Overview

React-Spline is a React component library for integrating Spline 3D scenes into React applications. It provides a seamless way to embed interactive 3D content created with Spline into React projects, allowing developers to enhance their web applications with immersive 3D experiences.

Pros

  • Easy integration of Spline 3D scenes into React applications
  • Supports interactive 3D content with minimal setup
  • Provides a responsive and performant 3D rendering solution
  • Offers customization options for scene loading and interaction

Cons

  • Limited documentation and examples available
  • Requires familiarity with Spline for creating 3D content
  • May have performance issues with complex 3D scenes on low-end devices
  • Dependency on external Spline services for content creation and hosting

Code Examples

Loading a Spline scene:

import Spline from '@splinetool/react-spline';

function App() {
  return (
    <Spline scene="https://prod.spline.design/example-scene-id" />
  );
}

Handling scene load events:

import Spline from '@splinetool/react-spline';

function App() {
  const onLoad = (splineApp) => {
    console.log('Spline scene loaded:', splineApp);
  };

  return (
    <Spline scene="https://prod.spline.design/example-scene-id" onLoad={onLoad} />
  );
}

Interacting with Spline objects:

import Spline from '@splinetool/react-spline';

function App() {
  const onMouseDown = (e) => {
    if (e.target.name === 'Cube') {
      console.log('Cube clicked!');
    }
  };

  return (
    <Spline
      scene="https://prod.spline.design/example-scene-id"
      onMouseDown={onMouseDown}
    />
  );
}

Getting Started

To use React-Spline in your project, follow these steps:

  1. Install the package:

    npm install @splinetool/react-spline
    
  2. Import and use the Spline component in your React application:

    import React from 'react';
    import Spline from '@splinetool/react-spline';
    
    function App() {
      return (
        <div>
          <h1>My 3D Scene</h1>
          <Spline scene="https://prod.spline.design/your-scene-id" />
        </div>
      );
    }
    
    export default App;
    
  3. Replace 'your-scene-id' with the actual ID of your Spline scene.

Competitor Comparisons

🇨🇭 A React renderer for Three.js

Pros of react-three-fiber

  • More flexible and customizable for complex 3D scenes
  • Larger community and ecosystem with extensive documentation
  • Direct integration with Three.js, allowing for more advanced features

Cons of react-three-fiber

  • Steeper learning curve, especially for those new to 3D graphics
  • Requires more manual setup and configuration
  • Performance may be less optimized for simpler scenes compared to react-spline

Code Comparison

react-three-fiber:

import { Canvas } from '@react-three/fiber'
import { Box } from '@react-three/drei'

function Scene() {
  return (
    <Canvas>
      <Box position={[0, 0, 0]} />
    </Canvas>
  )
}

react-spline:

import Spline from '@splinetool/react-spline';

function Scene() {
  return (
    <Spline scene="https://prod.spline.design/example-scene.splinecode" />
  )
}

react-three-fiber offers more granular control over scene elements, while react-spline provides a simpler API for importing pre-designed Spline scenes. react-three-fiber is better suited for developers who need full control over their 3D environments, while react-spline is ideal for quickly integrating ready-made 3D designs into React applications.

101,622

JavaScript 3D Library.

Pros of three.js

  • More mature and widely adopted, with a larger community and ecosystem
  • Offers greater flexibility and control over 3D rendering and interactions
  • Supports a wider range of 3D features and capabilities

Cons of three.js

  • Steeper learning curve, requiring more in-depth knowledge of 3D graphics
  • More complex setup and configuration for basic scenes
  • Requires more code to achieve similar results compared to React Spline

Code Comparison

three.js:

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

React Spline:

import Spline from '@splinetool/react-spline';

export default function App() {
  return (
    <Spline scene="https://prod.spline.design/example-scene.splinecode" />
  );
}

The three.js example shows the basic setup for a 3D scene, while the React Spline example demonstrates how easily a pre-designed 3D scene can be integrated into a React application. three.js offers more control but requires more code, while React Spline provides a simpler integration at the cost of flexibility.

Babylon.js is a powerful, beautiful, simple, and open game and rendering engine packed into a friendly JavaScript framework.

Pros of Babylon.js

  • More mature and feature-rich 3D engine with extensive documentation
  • Larger community and ecosystem, providing better support and resources
  • Supports a wider range of platforms and use cases beyond web applications

Cons of Babylon.js

  • Steeper learning curve due to its comprehensive feature set
  • Potentially heavier and more complex for simple 3D scenes or interactions
  • Requires more setup and configuration compared to React-Spline

Code Comparison

Babylon.js:

const canvas = document.getElementById("renderCanvas");
const engine = new BABYLON.Engine(canvas, true);
const scene = new BABYLON.Scene(engine);
const camera = new BABYLON.FreeCamera("camera", new BABYLON.Vector3(0, 5, -10), scene);
engine.runRenderLoop(() => scene.render());

React-Spline:

import Spline from '@splinetool/react-spline';

function App() {
  return <Spline scene="https://prod.spline.design/example-scene-url" />;
}

React-Spline offers a more straightforward integration for React applications, while Babylon.js provides greater control and flexibility for complex 3D scenes and interactions. The choice between the two depends on the specific project requirements, desired level of customization, and developer expertise.

9,523

JavaScript game engine built on WebGL, WebGPU, WebXR and glTF

Pros of PlayCanvas Engine

  • More comprehensive 3D engine with broader capabilities for game development
  • Larger community and ecosystem, providing better support and resources
  • Better performance for complex 3D scenes and games

Cons of PlayCanvas Engine

  • Steeper learning curve due to its more extensive feature set
  • Potentially overkill for simple 3D web experiences
  • Less seamless integration with React compared to React Spline

Code Comparison

React Spline:

import Spline from '@splinetool/react-spline';

export default function App() {
  return (
    <Spline scene="https://prod.spline.design/example.splinecode" />
  );
}

PlayCanvas Engine:

var canvas = document.getElementById('application');
var app = new pc.Application(canvas);

app.start();

var box = new pc.Entity('cube');
box.addComponent('model', { type: 'box' });
app.root.addChild(box);

The React Spline example shows how easily a 3D scene can be embedded in a React application. In contrast, the PlayCanvas Engine code demonstrates the more low-level approach to creating a 3D scene, offering greater control but requiring more setup.

43,739

The HTML5 Creation Engine: Create beautiful digital content with the fastest, most flexible 2D WebGL renderer.

Pros of PixiJS

  • Mature and widely adopted 2D rendering engine with extensive documentation
  • Excellent performance for complex 2D graphics and animations
  • Large ecosystem of plugins and community support

Cons of PixiJS

  • Steeper learning curve for beginners compared to React Spline
  • Primarily focused on 2D graphics, while React Spline offers 3D capabilities
  • Requires more manual setup and configuration for basic scenes

Code Comparison

React Spline:

import Spline from '@splinetool/react-spline';

export default function App() {
  return (
    <Spline scene="https://prod.spline.design/example.splinecode" />
  );
}

PixiJS:

import * as PIXI from 'pixi.js';

const app = new PIXI.Application({ width: 800, height: 600 });
document.body.appendChild(app.view);

const sprite = PIXI.Sprite.from('image.png');
app.stage.addChild(sprite);

React Spline offers a more straightforward integration with React applications, requiring minimal setup for 3D scenes. PixiJS provides greater control and flexibility for 2D graphics but requires more code to set up a basic scene. While React Spline focuses on easy 3D integration, PixiJS excels in high-performance 2D rendering and complex animations.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

react-spline

react-spline allows you to export and use Spline scenes directly in your React websites.

🌈 Spline is a friendly 3d collaborative design tool for the web.

WebsiteTwitterCommunityDocumentation

Table of Contents

Install

yarn add @splinetool/react-spline @splinetool/runtime

or

npm install @splinetool/react-spline @splinetool/runtime

Usage

To use react-spline, first you have to go to the Spline editor, click on the Export button, select "Code" and then "React".

You should see this:

You can copy the URL and pass it to the <Spline /> component in react:

import Spline from '@splinetool/react-spline';

export default function App() {
  return (
    <div>
      <Spline scene="https://prod.spline.design/6Wq1Q7YGyM-iab9i/scene.splinecode" />
    </div>
  );
}

You should be able to see the scene you exported in your React app.

NOTE: If you are experiencing CORS issues, you can download the .splinecode file and self-host it; this will fix any CORS issue. To download, go to Spline's code export panel and click on the download icon visible in the prod.spline textarea.

Next.js

You can use this library in Next.js as well to take advantage of Server Side Rendering. By default the library will render on the client only, but if you use the import @splinetool/react/next the server will render an autogenerated blurred placeholder.

Here is an example. Export as Next.js from the Spline editor to autogenerate the placeholder.

import Spline from '@splinetool/react-spline/next';

export default function App() {
  return (
    <div>
      <Spline scene="https://prod.spline.design/KFonZGtsoUXP-qx7/scene.splinecode" />
    </div>
  );
}

Read and modify Spline objects

You can query any Spline object via findObjectByName or findObjectById.

(You can get the ID of the object by right-clicking on it and selecting Copy Development Object ID).

import { useRef } from 'react';
import Spline from '@splinetool/react-spline';

export default function App() {
  const cube = useRef();

  function onLoad(spline) {
    const obj = spline.findObjectByName('Cube');
    // or
    // const obj = spline.findObjectById('8E8C2DDD-18B6-4C54-861D-7ED2519DE20E');

    // save it in a ref for later use
    cube.current = obj;
  }

  function moveObj() {
    console.log(cube.current); // Spline Object => { name: 'Cube', id: '8E8C2DDD-18B6-4C54-861D-7ED2519DE20E', position: {}, ... }

    // move the object in 3D space
    cube.current.position.x += 10;
  }

  return (
    <div>
      <Spline
        scene="https://prod.spline.design/6Wq1Q7YGyM-iab9i/scene.splinecode"
        onLoad={onLoad}
      />
      <button type="button" onClick={moveObj}>
        Move Cube
      </button>
    </div>
  );
}

Listen to Spline Events

You can listen to any Spline Event you set in the Events panel of the editor by attaching a listener to the Spline component.

import Spline from '@splinetool/react-spline';

export default function App() {
  function onSplineMouseDown(e) {
    if (e.target.name === 'Cube') {
      console.log('I have been clicked!');
    }
  }

  return (
    <div>
      <Spline
        scene="https://prod.spline.design/6Wq1Q7YGyM-iab9i/scene.splinecode"
        onSplineMouseDown={onSplineMouseDown}
      />
    </div>
  );
}

You can find a list of all of the Spline Event listeners in the Spline Component Props section.

Trigger Spline events from outside

You can trigger any animation Event you set in the Events panel in the Spline Editor.

You can use the emitEvent function via the spline ref, passing the event type and the ID of your object.

(You can get the ID of the object in the Develop pane of the right sidebar).

import { useRef } from 'react';
import Spline from '@splinetool/react-spline';

export default function App() {
  const spline = useRef();

  function onLoad(splineApp) {
    // save the app in a ref for later use
    spline.current = splineApp;
  }

  function triggerAnimation() {
    spline.current.emitEvent('mouseHover', 'Cube');
  }

  return (
    <div>
      <Spline
        scene="https://prod.spline.design/6Wq1Q7YGyM-iab9i/scene.splinecode"
        onLoad={onLoad}
      />
      <button type="button" onClick={triggerAnimation}>
        Trigger Spline Animation
      </button>
    </div>
  );
}

Or you can query the spline object first, and then trigger the event:

import { useRef } from 'react';
import Spline from '@splinetool/react-spline';

export default function App() {
  const objectToAnimate = useRef();

  function onLoad(spline) {
    const obj = spline.findObjectByName('Cube');
    // save the object in a ref for later use
    objectToAnimate.current = obj;
  }

  function triggerAnimation() {
    objectToAnimate.current.emitEvent('mouseHover');
  }

  return (
    <div>
      <Spline
        scene="https://prod.spline.design/6Wq1Q7YGyM-iab9i/scene.splinecode"
        onLoad={onLoad}
      />
      <button type="button" onClick={triggerAnimation}>
        Trigger Spline Animation
      </button>
    </div>
  );
}

You can find a list of all of the Spline Events you can pass to the emitEvent function in the Spline Events section.

Lazy loading

To start loading react-spline after the whole website has finished loading, we can use lazy-loading. This technique can be achieved using React.lazy() in combination with dynamic imports:

import React, { Suspense } from 'react';

const Spline = React.lazy(() => import('@splinetool/react-spline'));

export default function App() {
  return (
    <div>
      <Suspense fallback={<div>Loading...</div>}>
        <Spline scene="https://prod.spline.design/6Wq1Q7YGyM-iab9i/scene.splinecode" />
      </Suspense>
    </div>
  );
}

More info in the relative React documentation.

API

Spline Component Props

These are all the props you can pass to the <Spline /> component.

NameTypeDescription
scenestringScene file
onLoad?(spline: Application) => voidGets called once the scene has loaded. The spline parameter is an instance of the Spline Application
renderOnDemand?booleanWether or not to enable on demand rendering. Default true.
className?stringCSS classes
style?objectCSS style
id?stringCanvas id
ref?React.Ref<HTMLDivElement>A ref pointing to div container element.
onSplineMouseDown?(e: SplineEvent) => voidGets called once a Spline Mouse Down event is fired
onSplineMouseHover?(e: SplineEvent) => voidGets called once a Spline Mouse Hover event is fired
onSplineMouseUp?(e: SplineEvent) => voidGets called once a Spline Mouse Up event is fired
onSplineKeyDown?(e: SplineEvent) => voidGets called once a Spline Key Down event is fired
onSplineKeyUp?(e: SplineEvent) => voidGets called once a Spline Key Up event is fired
onSplineStart?(e: SplineEvent) => voidGets called once a Spline Start event is fired
onSplineLookAt?(e: SplineEvent) => voidGets called once a Spline Look At event is fired
onSplineFollow?(e: SplineEvent) => voidGets called once a Spline Mouse Up event is fired
onSplineScroll?(e: SplineEvent) => voidGets called once a Spline Scroll event is fired

Spline App Methods

The object exposed as a first argument of the onLoad function, is a Spline Application. You can call all these different methods on it.

NameTypeDescription
emitEvent(eventName: SplineEventName, nameOrUuid: string) => voidTriggers a Spline event associated to an object with provided name or uuid.
emitEventReverse(eventName: SplineEventName, nameOrUuid: string) => voidTriggers a Spline event associated to an object with provided uuid in reverse order. Starts from last state to first state.
findObjectById(uuid: string) => SPEObjectSearches through scene's children and returns the object with that uuid.
findObjectByName(name: string) => SPEObjectSearches through scene's children and returns the first object with that name.
setZoom(zoom: number) => voidSets the initial zoom of the scene.

Spline Events

These are all the Spline event types that you can pass to the emitEvent or emitEventReverse function.

NameDescription
mouseDownRefers to the Spline Mouse Down event type
mouseHoverRefers to the Spline Mouse Hover event type
mouseUpRefers to the Spline Mouse Up event type
keyDownRefers to the Spline Key Down event type
keyUpRefers to the Spline Key Up event type
startRefers to the Spline Start event type
lookAtRefers to the Spline Look At event type
followRefers to the Spline Mouse Up event type

Contributing

We use yarn, install the dependencies like this:

yarn

Development

Serve the example folder at localhost:3000

yarn dev

Build Library

yarn build

Publish on npm

yarn publish

NPM DownloadsLast 30 Days