# Vanilla JS / HTML Integration
Two methods depending on how much control you need.
---
## Method A — Web Component (Recommended for most cases)
No npm required. Just add to HTML. Supports lazy loading, transparent backgrounds, and mouse interactivity.
```html
```
---
## Method B — Runtime API (When you need programmatic control)
Use when you need to manipulate objects, trigger animations, or respond to events from your own JS.
Install:
```bash
npm install @splinetool/runtime
```
Or via CDN (no install):
```html
```
Basic usage:
```js
import { Application } from '@splinetool/runtime';
const canvas = document.getElementById('canvas3d');
const spline = new Application(canvas);
spline.load('https://prod.spline.design/REPLACE_ME/scene.splinecode').then(() => {
console.log('Scene loaded');
});
```
With object interaction:
```js
spline.load(sceneUrl).then(() => {
const obj = spline.findObjectByName('Cube');
// or by ID: spline.findObjectById('uuid-here')
obj.position.x += 50;
obj.rotation.y += Math.PI / 4; // NOTE: radians, NOT degrees
obj.scale.x = 2;
});
```
With event listeners:
```js
spline.load(sceneUrl).then(() => {
spline.addEventListener('mouseDown', (e) => {
console.log('Clicked:', e.target.name);
});
});
```
Trigger animations programmatically:
```js
spline.load(sceneUrl).then(() => {
const obj = spline.findObjectByName('MyObject');
obj.emitEvent('mouseHover'); // forward
obj.emitEventReverse('mouseHover'); // reverse
});
```
---
## Full-Page Background Setup
The most common use case — Spline scene behind all content.
```html
Your Content Here
```
---
## Available Event Types
| Event | Use case |
|---|---|
| `mouseDown` | Click/tap on object |
| `mouseUp` | Release after click |
| `mouseHover` | Cursor enters object area |
| `mousePress` | Holding click down |
| `keyDown` | Key pressed |
| `keyUp` | Key released |
| `start` | Scene has loaded and started |
| `scroll` | Page scrolled |
---
## Preloading (Reduces Perceived Load Time)
Add to `` to start fetching the scene file before scripts run:
```html
```
See [PERFORMANCE.md](PERFORMANCE.md) for full optimization strategy.
See [COMMON_PROBLEMS.md](COMMON_PROBLEMS.md) for debugging.