Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@splinetool/react-spline

Package Overview
Dependencies
Maintainers
0
Versions
26
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@splinetool/react-spline

  • 4.0.0
  • latest
  • npm
  • Socket score

Version published
Weekly downloads
20K
increased by3.55%
Maintainers
0
Weekly downloads
 
Created
Source

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

FAQs

Package last updated on 20 Jun 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc