Installation

Model requirements

• Format: GLB files (binary glTF)
• Size: Under 50MB recommended for web
• Optimisation: See the optimisation guide for performance improvements

CDN (Recommended)

The simplest approach - all examples here use CDN imports. If you copy the basic viewer example, this is how it works: you only need a single HTML file and your models, with no downloads or build steps required.

Both Three.js and BelowJS use ES modules. Add the import map and stylesheet:

<script type="importmap">
{
    "imports": {
        "three": "https://cdn.jsdelivr.net/npm/three@0.179.1/+esm",
        "belowjs": "https://cdn.jsdelivr.net/npm/belowjs@1.1.0/dist/belowjs.js"
    }
}
</script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/belowjs@1.1.0/dist/belowjs.css">

Then import and use:

import { ModelViewer } from 'belowjs';

const viewer = new ModelViewer('body', {
    models: { 'wreck': { url: 'shipwreck.glb' } }
});

npm

Use npm when integrating BelowJS into an existing project with a build system (Webpack, Vite, etc.).

npm install belowjs three

import { ModelViewer } from 'belowjs';
import 'belowjs/dist/belowjs.css';

const config = {
    models: {
        'kxi': {
            url: 'shipwreck.glb'
        }
    }
};

const viewer = new ModelViewer('#container', config);

Manual installation

If you prefer to download files directly, you can get them from GitHub or clone the repository and build them yourself:

git clone https://github.com/patrick-morrison/belowjs
cd belowjs
npm install
npm run build

This builds the necessary files into the /dist directory:

• belowjs.js (~419 KB) — ES modules version
• belowjs.css (~20 KB) — Complete stylesheet

Static deployment

Deploy using CDN (no downloads needed):

shipwrecks-vr/
├── index.html          # Uses CDN imports
└── models/
    ├── kxi.glb
    └── kozvii.glb

VR setup

VR requires HTTPS in production. For local development:

python -m http.server 8000

Quest: Chrome can forward localhost to Quest via USB debugging. Setup guide.

Browser support

Feature	Chrome	Firefox	Safari	Edge
Basic viewing	✅	✅	✅	✅
VR mode	✅	✅	❌	✅

Troubleshooting

Don't know where to start?

• Copy the basic example and swap out your model files

Model not loading properly?

• Test your GLB file in the drag & drop example first
• Check it is scaled properly - see the model setup guide
• Check file paths - see the basic example on the examples page
• Open browser console for error messages

VR button not showing?

• Use HTTPS (required for WebXR)
• Check browser VR support in the table above
• View in a VR headset or connect PCVR - see VR headsets guide

Performance issues?

• Check model stats in the drag & drop example
• Follow the optimisation guide for reducing file sizes and polygon counts

Next Steps

Ready to get started? See the examples page for three production-ready viewers you can use.

Each example is designed to work by simply changing a few lines of HTML to point to your own models. Download the HTML file, add your GLB files to the same folder, and you're ready to go!