{"_id":"@anacoelhovicente/react-spline","name":"@anacoelhovicente/react-spline","dist-tags":{"latest":"4.0.2"},"versions":{"4.0.2":{"name":"@anacoelhovicente/react-spline","version":"4.0.2","packageManager":"yarn@3.3.0","type":"module","react-native":"./dist/react-spline.js","types":"./dist/Spline.d.ts","exports":{".":{"types":"./dist/Spline.d.ts","import":"./dist/react-spline.js"},"./next":{"types":"./dist/next/SplineNext.d.ts","import":"./dist/react-spline-next.js"}},"scripts":{"start":"vite","dev":"vite","serve":"vite preview","build":"rimraf dist/ && vite build && yarn build-types","build-types":"tsc --skipLibCheck --isolatedModules false --noEmit false --emitDeclarationOnly --declaration --outDir dist/","publish":"yarn build && np --no-tests"},"peerDependencies":{"@splinetool/runtime":"*","next":">=14.2.0","react":"*","react-dom":"*"},"peerDependenciesMeta":{"next":{"optional":true}},"dependencies":{"blurhash":"2.0.5","lodash.debounce":"4.0.8","react-merge-refs":"2.1.1","thumbhash":"0.1.1"},"devDependencies":{"@splinetool/runtime":"^1.3.10","@types/animejs":"^3.1.12","@types/lodash.debounce":"^4.0.9","@types/node":"^20.14.1","@types/react":"^18.3.3","@types/react-dom":"^18.3.0","@vitejs/plugin-react":"^4.3.0","animejs":"^3.2.2","modern-normalize":"^1.1.0","next":"15.0.0-rc.0","np":"^10.0.5","react":"19.0.0-rc-f994737d14-20240522","react-dom":"19.0.0-rc-f994737d14-20240522","rimraf":"^5.0.7","rollup-plugin-rename-node-modules":"^1.3.1","rollup-preserve-directives":"^1.1.1","typescript":"^5.4.5","vite":"^5.2.12"},"_id":"@anacoelhovicente/react-spline@4.0.2","gitHead":"247d4a1f8df1b08f521eae06878a8e875ef7d933","description":"[![](https://raw.githubusercontent.com/splinetool/react-spline/main/.github/screenshots/hero.png)](https://my.spline.design/splinereactlogocopycopy-eaa074bf6b2cc82d870c96e262a625ae/)","_nodeVersion":"22.11.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-9103LIr4+Y3qm9I3nhzMk/OXDM7cChn7yEU0PxAiiz9YWPxzB90fBrqDgn1AMyhkmYeQaDJW1e7vreQJGC8hbg==","shasum":"7b040c19231c80534f73c7934d43bb93069e0808","tarball":"https://registry.npmjs.org/@anacoelhovicente/react-spline/-/react-spline-4.0.2.tgz","fileCount":11,"unpackedSize":26999,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCQNFu8h9htDcKcZFjIpzucnyOHglnP2icc1d7iFEDbMQIhAKb+kFMdYNNBCih7wv9MWDKvD0PCbn9K7q+hiPsNgsGg"}]},"_npmUser":{"name":"anacoelhovicente","email":"contact.me@anavicente.me"},"directories":{},"maintainers":[{"name":"anacoelhovicente","email":"contact.me@anavicente.me"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/react-spline_4.0.2_1735833548925_0.4542007334295104"},"_hasShrinkwrap":false}},"time":{"created":"2025-01-02T15:59:08.825Z","4.0.2":"2025-01-02T15:59:09.121Z","modified":"2025-01-02T15:59:09.389Z"},"maintainers":[{"name":"anacoelhovicente","email":"contact.me@anavicente.me"}],"description":"[![](https://raw.githubusercontent.com/splinetool/react-spline/main/.github/screenshots/hero.png)](https://my.spline.design/splinereactlogocopycopy-eaa074bf6b2cc82d870c96e262a625ae/)","readme":"[![](https://raw.githubusercontent.com/splinetool/react-spline/main/.github/screenshots/hero.png)](https://my.spline.design/splinereactlogocopycopy-eaa074bf6b2cc82d870c96e262a625ae/)\n\n# react-spline\n\n**react-spline** allows you to export and use Spline scenes directly in your React websites.\n\n🌈 [Spline](https://spline.design/) is a friendly 3d collaborative design tool for the web.\n\n[Website](https://spline.design/) &mdash;\n[Twitter](https://twitter.com/splinetool) &mdash;\n[Community](https://discord.gg/M9hNDMqvnw) &mdash;\n[Documentation](https://docs.spline.design/)\n\n## Table of Contents\n\n- [Install](#install)\n- [Usage](#usage)\n  - [Next.js](#nextjs)\n  - [Read and modify Spline objects](#read-and-modify-spline-objects)\n  - [Listen to events](#listen-to-events)\n  - [Trigger Spline events from outside](#trigger-spline-events-from-outside)\n  - [Lazy loading](#lazy-loading)\n- [API](#api)\n  - [Spline Component Props](#spline-component-props)\n  - [Spline App Methods](#spline-app-methods)\n  - [Spline Events](#spline-events)\n- [Contributing](#contributing)\n\n## Install\n\n```bash\nyarn add @splinetool/react-spline @splinetool/runtime\n```\n\nor\n\n```bash\nnpm install @splinetool/react-spline @splinetool/runtime\n```\n\n## Usage\n\nTo use react-spline, first you have to go to the Spline editor, click on the **Export** button, select \"**Code**\" and then \"**React**\".\n\nYou should see this:\n\n<img width=\"250\" src=\"https://raw.githubusercontent.com/splinetool/react-spline/main/.github/screenshots/react-export-pane.png\">\n\nYou can copy the URL and pass it to the `<Spline />` component in react:\n\n```jsx\nimport Spline from '@splinetool/react-spline';\n\nexport default function App() {\n  return (\n    <div>\n      <Spline scene=\"https://prod.spline.design/6Wq1Q7YGyM-iab9i/scene.splinecode\" />\n    </div>\n  );\n}\n```\n\nYou should be able to see the scene you exported in your React app.\n\n[![](https://raw.githubusercontent.com/splinetool/react-spline/main/.github/screenshots/example-basic.png)](https://codesandbox.io/s/sweet-rain-28pcxt?file=/src/App.js)\n\n**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.\n\n### Next.js\n\nYou 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.\n\nHere is an example. Export as `Next.js` from the Spline editor to autogenerate the placeholder.\n\n```js\nimport Spline from '@splinetool/react-spline/next';\n\nexport default function App() {\n  return (\n    <div>\n      <Spline scene=\"https://prod.spline.design/KFonZGtsoUXP-qx7/scene.splinecode\" />\n    </div>\n  );\n}\n```\n\n### Read and modify Spline objects\n\nYou can query any Spline object via `findObjectByName` or `findObjectById`.\n\n_(You can get the ID of the object by right-clicking on it and selecting `Copy Development Object ID`)._\n\n```jsx\nimport { useRef } from 'react';\nimport Spline from '@splinetool/react-spline';\n\nexport default function App() {\n  const cube = useRef();\n\n  function onLoad(spline) {\n    const obj = spline.findObjectByName('Cube');\n    // or\n    // const obj = spline.findObjectById('8E8C2DDD-18B6-4C54-861D-7ED2519DE20E');\n\n    // save it in a ref for later use\n    cube.current = obj;\n  }\n\n  function moveObj() {\n    console.log(cube.current); // Spline Object => { name: 'Cube', id: '8E8C2DDD-18B6-4C54-861D-7ED2519DE20E', position: {}, ... }\n\n    // move the object in 3D space\n    cube.current.position.x += 10;\n  }\n\n  return (\n    <div>\n      <Spline\n        scene=\"https://prod.spline.design/6Wq1Q7YGyM-iab9i/scene.splinecode\"\n        onLoad={onLoad}\n      />\n      <button type=\"button\" onClick={moveObj}>\n        Move Cube\n      </button>\n    </div>\n  );\n}\n```\n\n### Listen to Spline Events\n\nYou can listen to any Spline Event you set in the Events panel of the editor by attaching a listener to the Spline component.\n\n```jsx\nimport Spline from '@splinetool/react-spline';\n\nexport default function App() {\n  function onSplineMouseDown(e) {\n    if (e.target.name === 'Cube') {\n      console.log('I have been clicked!');\n    }\n  }\n\n  return (\n    <div>\n      <Spline\n        scene=\"https://prod.spline.design/6Wq1Q7YGyM-iab9i/scene.splinecode\"\n        onSplineMouseDown={onSplineMouseDown}\n      />\n    </div>\n  );\n}\n```\n\nYou can find a list of all of the Spline Event listeners in the [Spline Component Props](#spline-component-props) section.\n\n### Trigger Spline events from outside\n\nYou can trigger any animation Event you set in the Events panel in the Spline Editor.\n\nYou can use the `emitEvent` function via the spline ref, passing the [event type](#spline-events) and the ID of your object.\n\n_(You can get the ID of the object in the `Develop` pane of the right sidebar)._\n\n```jsx\nimport { useRef } from 'react';\nimport Spline from '@splinetool/react-spline';\n\nexport default function App() {\n  const spline = useRef();\n\n  function onLoad(splineApp) {\n    // save the app in a ref for later use\n    spline.current = splineApp;\n  }\n\n  function triggerAnimation() {\n    spline.current.emitEvent('mouseHover', 'Cube');\n  }\n\n  return (\n    <div>\n      <Spline\n        scene=\"https://prod.spline.design/6Wq1Q7YGyM-iab9i/scene.splinecode\"\n        onLoad={onLoad}\n      />\n      <button type=\"button\" onClick={triggerAnimation}>\n        Trigger Spline Animation\n      </button>\n    </div>\n  );\n}\n```\n\nOr you can query the spline object first, and then trigger the event:\n\n```jsx\nimport { useRef } from 'react';\nimport Spline from '@splinetool/react-spline';\n\nexport default function App() {\n  const objectToAnimate = useRef();\n\n  function onLoad(spline) {\n    const obj = spline.findObjectByName('Cube');\n    // save the object in a ref for later use\n    objectToAnimate.current = obj;\n  }\n\n  function triggerAnimation() {\n    objectToAnimate.current.emitEvent('mouseHover');\n  }\n\n  return (\n    <div>\n      <Spline\n        scene=\"https://prod.spline.design/6Wq1Q7YGyM-iab9i/scene.splinecode\"\n        onLoad={onLoad}\n      />\n      <button type=\"button\" onClick={triggerAnimation}>\n        Trigger Spline Animation\n      </button>\n    </div>\n  );\n}\n```\n\nYou can find a list of all of the Spline Events you can pass to the `emitEvent` function in the [Spline Events](#spline-events) section.\n\n### Lazy loading\n\nTo start loading react-spline after the whole website has finished loading, we can use lazy-loading. This technique can be achieved using [`React.lazy()`](https://it.reactjs.org/docs/code-splitting.html#reactlazy) in combination with dynamic imports:\n\n```jsx\nimport React, { Suspense } from 'react';\n\nconst Spline = React.lazy(() => import('@splinetool/react-spline'));\n\nexport default function App() {\n  return (\n    <div>\n      <Suspense fallback={<div>Loading...</div>}>\n        <Spline scene=\"https://prod.spline.design/6Wq1Q7YGyM-iab9i/scene.splinecode\" />\n      </Suspense>\n    </div>\n  );\n}\n```\n\nMore info in the [relative React documentation](https://it.reactjs.org/docs/code-splitting.html).\n\n## API\n\n### Spline Component Props\n\nThese are all the props you can pass to the `<Spline />` component.\n\n| Name                  | Type                            | Description                                                                                                                   |\n| --------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |\n| `scene`               | `string`                        | Scene file                                                                                                                    |\n| `onLoad?`             | `(spline: Application) => void` | Gets called once the scene has loaded. The `spline` parameter is an instance of the [Spline Application](#spline-app-methods) |\n| `renderOnDemand?`     | `boolean`                       | Wether or not to enable [on demand rendering](https://threejs.org/manual/#en/rendering-on-demand). Default `true`.            |\n| `className?`          | `string`                        | CSS classes                                                                                                                   |\n| `style?`              | `object`                        | CSS style                                                                                                                     |\n| `id?`                 | `string`                        | Canvas id                                                                                                                     |\n| `ref?`                | `React.Ref<HTMLDivElement>`     | A ref pointing to div container element.                                                                                      |\n| `onSplineMouseDown?`  | `(e: SplineEvent) => void`      | Gets called once a Spline `Mouse Down` event is fired                                                                         |\n| `onSplineMouseHover?` | `(e: SplineEvent) => void`      | Gets called once a Spline `Mouse Hover` event is fired                                                                        |\n| `onSplineMouseUp?`    | `(e: SplineEvent) => void`      | Gets called once a Spline `Mouse Up` event is fired                                                                           |\n| `onSplineKeyDown?`    | `(e: SplineEvent) => void`      | Gets called once a Spline `Key Down` event is fired                                                                           |\n| `onSplineKeyUp?`      | `(e: SplineEvent) => void`      | Gets called once a Spline `Key Up` event is fired                                                                             |\n| `onSplineStart?`      | `(e: SplineEvent) => void`      | Gets called once a Spline `Start` event is fired                                                                              |\n| `onSplineLookAt?`     | `(e: SplineEvent) => void`      | Gets called once a Spline `Look At` event is fired                                                                            |\n| `onSplineFollow?`     | `(e: SplineEvent) => void`      | Gets called once a Spline `Mouse Up` event is fired                                                                           |\n| `onSplineScroll?`     | `(e: SplineEvent) => void`      | Gets called once a Spline `Scroll` event is fired                                                                             |\n\n### Spline App Methods\n\nThe object exposed as a first argument of the `onLoad` function, is a Spline Application. You can call all these different methods on it.\n\n| Name               | Type                                                       | Description                                                                                                                 |\n| ------------------ | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| `emitEvent`        | `(eventName: SplineEventName, nameOrUuid: string) => void` | Triggers a Spline event associated to an object with provided name or uuid.                                                 |\n| `emitEventReverse` | `(eventName: SplineEventName, nameOrUuid: string) => void` | Triggers a Spline event associated to an object with provided uuid in reverse order. Starts from last state to first state. |\n| `findObjectById`   | `(uuid: string) => SPEObject`                              | Searches through scene's children and returns the object with that uuid.                                                    |\n| `findObjectByName` | `(name: string) => SPEObject`                              | Searches through scene's children and returns the first object with that name.                                              |\n| `setZoom`          | `(zoom: number) => void`                                   | Sets the initial zoom of the scene.                                                                                         |\n\n### Spline Events\n\nThese are all the Spline event types that you can pass to the `emitEvent` or `emitEventReverse` function.\n\n| Name         | Description                                   |\n| ------------ | --------------------------------------------- |\n| `mouseDown`  | Refers to the Spline `Mouse Down` event type  |\n| `mouseHover` | Refers to the Spline `Mouse Hover` event type |\n| `mouseUp`    | Refers to the Spline `Mouse Up` event type    |\n| `keyDown`    | Refers to the Spline `Key Down` event type    |\n| `keyUp`      | Refers to the Spline `Key Up` event type      |\n| `start`      | Refers to the Spline `Start` event type       |\n| `lookAt`     | Refers to the Spline `Look At` event type     |\n| `follow`     | Refers to the Spline `Mouse Up` event type    |\n\n## Contributing\n\nWe use [yarn](https://yarnpkg.com/), install the dependencies like this:\n\n```bash\nyarn\n```\n\n### Development\n\nServe the `example` folder at localhost:3000\n\n```bash\nyarn dev\n```\n\n### Build Library\n\n```bash\nyarn build\n```\n\n### Publish on npm\n\n```bash\nyarn publish\n```\n","readmeFilename":"README.md"}