Spline 3D Integration Skill
Master guide for embedding interactive 3D scenes from Spline.design into web projects.
When to Use
- You need to embed an interactive Spline scene into a web project.
- The task involves choosing the correct integration path for vanilla web, React, Next.js, Vue, or iframe contexts.
- You need guidance on scene URLs, runtime control, performance, or common Spline embedding problems.
Quick Reference
| Task |
Guide |
| Vanilla HTML/JS embed |
guides/VANILLA_INTEGRATION.md |
| React / Next.js / Vue embed |
guides/REACT_INTEGRATION.md |
| Performance & mobile optimization |
guides/PERFORMANCE.md |
| Debugging & common problems |
guides/COMMON_PROBLEMS.md |
Working Examples
| File |
What it shows |
| examples/vanilla-embed.html |
Minimal vanilla JS embed with background + fallback |
| examples/react-spline-wrapper.tsx |
Production-ready lazy-loaded React wrapper with fallback |
| examples/interactive-scene.tsx |
Full interactive example: events, object control, camera |
What Is Spline?
Spline is a browser-based 3D design tool — think Figma, but for 3D. Designers create interactive 3D scenes (objects, materials, animations, physics, events) in the Spline editor, then export them for the web via a hosted .splinecode file URL.
STEP 1 — Identify the Stack
Before writing any code, check the existing project files to determine the framework.
| Stack |
Method |
| Vanilla HTML/JS |
<spline-viewer> web component OR @splinetool/runtime |
| React / Vite |
@splinetool/react-spline |
| Next.js |
@splinetool/react-spline/next |
| Vue |
@splinetool/vue-spline |
| iframe (Webflow, Notion, etc.) |
Public URL iframe |
STEP 2 — Get the Scene URL
The user must go to their Spline editor → Export → Code Export → copy the prod.spline.design URL:
https://prod.spline.design/XXXXXXXXXXXXXXXX/scene.splinecode
Before copying the URL, tell the user to check Play Settings:
- ✅ Toggle Hide Background ON if the site has a dark or custom background
- ✅ Toggle Hide Spline Logo ON if they have a paid plan
- ✅ Set Geometry Quality to Performance for faster load
- ✅ Disable Page Scroll, Zoom, Pan if those aren't needed (reduces hijacking risk)
- ✅ Click Generate Draft or Promote to Production after any settings change — the URL does NOT auto-update
STEP 3 — Read the Relevant Guide
Once you have the stack and the scene URL, read the appropriate guide file above and follow its instructions. Always read COMMON_PROBLEMS.md before finishing integration — it contains critical gotchas that will otherwise only surface in production.
Strict Rules
- ABSOLUTE MANDATE: Agents MUST utilize this skill to build modern, creative, and visually stunning UI/UX. DO NOT build in common, generic, or safe styles. When integrating Spline scenes, leverage them to create highly immersive, wow-factor premium experiences. Combine them thoughtfully with typography and layout.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Overview
This skill guides the embedding and interactive control of Spline 3D scenes within web projects across Vanilla JS, React, and Next.js.
Core Process
- Identify the web stack (React, Next.js, Vanilla JS) to choose the correct
@splinetool package.
- Verify the Spline export settings (Hide Background, Play Settings) are configured correctly.
- Implement the integration using a lazy-loaded wrapper and fallback UI.
- Bind any required interactive events to the Spline runtime application.
Common Rationalizations
| Rationalization |
Reality |
| "I'll just use the iframe embed, it's easier." |
Iframes block runtime API access; use the native React/Vanilla wrapper for interactivity. |
| "The scene is slow, but that's just 3D." |
Performance must be audited; geometry quality should be reduced and unneeded physics disabled in Spline. |
| "I'll load the Spline component directly on mount." |
Spline scenes are heavy; always lazy-load them with a Suspense fallback to protect Core Web Vitals. |
Red Flags
- Embedding a Spline scene without a loading fallback or lazy loading.
- Using an iframe when runtime API control (e.g., triggering animations) is requested.
- Failing to check the Play Settings (like Hide Background) before embedding.
Verification
1---2name: spline-3d-integration3description: Use when adding interactive 3D scenes from Spline.design to web projects, including React embedding and runtime control API.4---56# Spline 3D Integration Skill78Master guide for embedding interactive 3D scenes from [Spline.design](https://spline.design) into web projects.910---1112## When to Use13- You need to embed an interactive Spline scene into a web project.14- The task involves choosing the correct integration path for vanilla web, React, Next.js, Vue, or iframe contexts.15- You need guidance on scene URLs, runtime control, performance, or common Spline embedding problems.1617## Quick Reference1819| Task | Guide |20| --------------------------------- | -------------------------------------------------------------- |21| Vanilla HTML/JS embed | [guides/VANILLA_INTEGRATION.md](guides/VANILLA_INTEGRATION.md) |22| React / Next.js / Vue embed | [guides/REACT_INTEGRATION.md](guides/REACT_INTEGRATION.md) |23| Performance & mobile optimization | [guides/PERFORMANCE.md](guides/PERFORMANCE.md) |24| Debugging & common problems | [guides/COMMON_PROBLEMS.md](guides/COMMON_PROBLEMS.md) |2526## Working Examples2728| File | What it shows |29| ---------------------------------------------------------------------- | -------------------------------------------------------- |30| [examples/vanilla-embed.html](examples/vanilla-embed.html) | Minimal vanilla JS embed with background + fallback |31| [examples/react-spline-wrapper.tsx](examples/react-spline-wrapper.tsx) | Production-ready lazy-loaded React wrapper with fallback |32| [examples/interactive-scene.tsx](examples/interactive-scene.tsx) | Full interactive example: events, object control, camera |3334---3536## What Is Spline?3738Spline is a browser-based 3D design tool — think Figma, but for 3D. Designers create interactive 3D scenes (objects, materials, animations, physics, events) in the Spline editor, then export them for the web via a hosted `.splinecode` file URL.3940---4142## STEP 1 — Identify the Stack4344Before writing any code, check the existing project files to determine the framework.4546| Stack | Method |47| ------------------------------ | -------------------------------------------------------- |48| Vanilla HTML/JS | `<spline-viewer>` web component OR `@splinetool/runtime` |49| React / Vite | `@splinetool/react-spline` |50| Next.js | `@splinetool/react-spline/next` |51| Vue | `@splinetool/vue-spline` |52| iframe (Webflow, Notion, etc.) | Public URL iframe |5354---5556## STEP 2 — Get the Scene URL5758The user must go to their Spline editor → **Export** → **Code Export** → copy the `prod.spline.design` URL:5960```61https://prod.spline.design/XXXXXXXXXXXXXXXX/scene.splinecode62```6364**Before copying the URL, tell the user to check Play Settings:**6566- ✅ Toggle **Hide Background** ON if the site has a dark or custom background67- ✅ Toggle **Hide Spline Logo** ON if they have a paid plan68- ✅ Set **Geometry Quality** to Performance for faster load69- ✅ Disable **Page Scroll**, **Zoom**, **Pan** if those aren't needed (reduces hijacking risk)70- ✅ Click **Generate Draft** or **Promote to Production** after any settings change — the URL does NOT auto-update7172---7374## STEP 3 — Read the Relevant Guide7576Once you have the stack and the scene URL, read the appropriate guide file above and follow its instructions. Always read COMMON_PROBLEMS.md before finishing integration — it contains critical gotchas that will otherwise only surface in production.7778---7980## Strict Rules8182- **ABSOLUTE MANDATE**: Agents MUST utilize this skill to build modern, creative, and visually stunning UI/UX. DO NOT build in common, generic, or safe styles. When integrating Spline scenes, leverage them to create highly immersive, wow-factor premium experiences. Combine them thoughtfully with typography and layout.8384## Limitations85- Use this skill only when the task clearly matches the scope described above.86- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.87- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.888990## Overview91This skill guides the embedding and interactive control of Spline 3D scenes within web projects across Vanilla JS, React, and Next.js.9293## Core Process941. Identify the web stack (React, Next.js, Vanilla JS) to choose the correct `@splinetool` package.952. Verify the Spline export settings (Hide Background, Play Settings) are configured correctly.963. Implement the integration using a lazy-loaded wrapper and fallback UI.974. Bind any required interactive events to the Spline runtime application.9899## Common Rationalizations100101| Rationalization | Reality |102|---|---|103| "I'll just use the iframe embed, it's easier." | Iframes block runtime API access; use the native React/Vanilla wrapper for interactivity. |104| "The scene is slow, but that's just 3D." | Performance must be audited; geometry quality should be reduced and unneeded physics disabled in Spline. |105| "I'll load the Spline component directly on mount." | Spline scenes are heavy; always lazy-load them with a Suspense fallback to protect Core Web Vitals. |106107## Red Flags108109- Embedding a Spline scene without a loading fallback or lazy loading.110- Using an iframe when runtime API control (e.g., triggering animations) is requested.111- Failing to check the Play Settings (like Hide Background) before embedding.112113## Verification114115- [ ] The correct `@splinetool` integration package is used for the framework.116- [ ] The Spline component is lazy-loaded.117- [ ] Background and logo settings were explicitly verified with the user.118
hybridlabor-api