3D AR Studio

3D AR Studio

Drop a full augmented-reality studio into any web page.

Place as many 3D models as you like in your real room through the camera, describe a new one and watch it appear, arrange everything by hand, then share the whole scene as a link, a QR code, or a live room someone else can build in with you.

Live demo · npm · MCP server

<script type="module" src="https://unpkg.com/3d-ar-studio/dist/ar-studio.min.js"></script>

That is a working AR studio. No build step, no API key, no account. It comes wired to a free library of a few hundred public-domain models and a free, keyless text-to-3D lane; point it at your own catalogue with one option when you are ready.

Why this exists

Every web-AR drop-in places exactly one model and then hands off to a native viewer, which ends the session. This one keeps the whole scene in your page:

• Many models, one room. Place, drag, pinch-resize, twist-rotate and duplicate as many models as you want in a single live camera view.
• Generate without leaving the camera. Type "a brass desk lamp" into the dock. The generation runs behind the live view and the finished model drops into the room.
• Real WebXR where it exists. An always-armed hit-test reticle, one XRAnchor per placed model, real-world light estimation, and depth occlusion so models hide behind your furniture.
• Real ARKit and ARCore everywhere else. iPhones have no WebXR, so tapping Place in your space opens Apple's AR Quick Look for real: true plane detection, true scale, true occlusion, the system's own "View in AR" sheet. The model is converted to USDZ on the device (a real conversion via three.js's USDZExporter, no server involved) and, because it is exported from the copy already standing in your scene, it arrives at the size you pinched it to and in the pose it was in, stood on the floor rather than hanging at the height it happened to be modelled at. Android without WebXR gets Scene Viewer. Desktop gets a grid preview and a QR hand-off to a phone.
• Scenes are links. Models, positions, rotations and scales round-trip through the URL. Compose on a laptop, scan the QR, it reopens exactly on your phone.
• Build together, live. Open a room, share a six-character code, and every add and move syncs to everyone in it.
• Characters actually move. Any humanoid GLB with no baked animation gets an idle clip retargeted onto its own skeleton. No rig allow-list, no T-poses.
• Agents can drive it. A bundled MCP server lets Claude, ChatGPT or your own agent generate a model, compose an arrangement, and hand a person one link that opens it in their room.

The rendering ladder, anchor lifecycle, retargeting pipeline, scene format and shared-room protocol are extracted from the AR surfaces running in production on three.ws, and generalized so they work on your site with your models.

Install

npm i 3d-ar-studio three

three is a peer dependency, so you keep one copy of it and pick the version. The CDN bundle (dist/ar-studio.min.js) has three.js inside it and needs nothing else.

import { createArStudio } from '3d-ar-studio'

const studio = createArStudio('#stage', { branding: { title: 'Acme AR', accent: '#00b894' }, })

studio.on('add', ({ placement }) => console.log('placed', placement.title))

The studio fills its host element absolutely, so give the host a height (any positioned box with a real height works; a with no height gets a sensible 70vh default rather than rendering invisibly).

Scaffold a deployable page

npx 3d-ar-studio create my-ar-site     # a folder you can publish as-is

cd my-ar-site npx 3d-ar-studio dev # look at it locally npx 3d-ar-studio deploy # push it and turn on GitHub Pages

deploy prints every git and gh command before it runs it. It needs git and the GitHub CLI; without them it tells you the three manual steps instead of failing silently.

Templates: static (one HTML file, no build), vite, react.

Both 3d-ar-studio and ar-studio run the CLI. The MCP server is a separate binary in its own package, so npx 3d-ar-studio-mcp resolves cleanly: see MCP server.

Your own models

The tray is filled from three.ws by default: a few hundred public-domain (CC0) props, free for commercial use, served with open CORS. Swap in your own with the assets option.

A JSON file anywhere. Five common shapes are read without reshaping:

createArStudio(el, { assets: 'https://cdn.acme.com/models.json' })

// Any of these work:

[ { "url": "https://cdn.acme.com/chair.glb", "name": "Aero chair" } ] { "items": [ … ] } { "objects": [ … ] } // three.ws object library { "creations": [ … ] } // three.ws forge gallery { "models": [ … ] }

Per entry, the model URL is read from the first present of src, url, glb, glb_url, glbUrl, file or model; the label from title, label, name or prompt; and the thumbnail from poster, thumb, thumbnail, image or preview_image_url. Anything that is not an https (or site-relative) URL is dropped rather than handed to the loader.

A list you hold in code:

import { staticSource } from '3d-ar-studio/sources'

createArStudio(el, { assets: staticSource({ label: 'Our furniture', items: [{ src: 'https://cdn.acme.com/chair.glb', title: 'Aero chair', poster: '…' }], }), })

Several tabs at once, in the order you want them:

createArStudio(el, { assets: ['recent', myCatalogue, 'objects', 'link'] })

Built-in keys: 'three.ws' (the default set), 'recent', 'objects', 'community', 'link'.

Anything else. A source is an object with a list():

createArStudio(el, {

assets: { id: 'search', label: 'Search', searchable: true, async list() { const rows = await fetch('/api/models').then((r) => r.json()) return rows.map((m) => ({ src: m.glb, title: m.name, poster: m.thumb })) }, }, })

Throwing from list() is fine: the tray renders a designed error state with a Retry button.

Your users can retarget it too, without touching your code: ?assets=https://…/manifest.json on the page URL. Only https URLs are accepted, and every model source is re-validated before it reaches the loader, so a hostile link can add a catalogue but can never smuggle a javascript: or data: model into the scene. Set allowUrlOverride: false to switch that off.

CORS

Models are loaded by the browser, so the host serving your .glb files has to allow cross-origin requests (access-control-allow-origin). If a model fails to load, that is almost always why, and the studio says so in the status line rather than failing silently.

Options

URL parameters

Methods

await studio.addModel({ src, title })        // place a model

studio.clear() // remove everything; returns what was there studio.getScene() // [{ src, title, x, z, yaw, scale }] await studio.setScene(items) // replace the arrangement studio.shareUrl() // a link that reopens it exactly await studio.generate('a brass desk lamp') // text to 3D, into the room studio.viewInYourSpace(src, title) // open the hosted launch page for one model await studio.startCamera() // needs a user gesture on iOS await studio.enterAR() // best AR path for this device studio.openArSheet() // the "Place in your space" hand-off sheet studio.closeArSheet() await studio.placeInYourSpace() // straight to the native viewer, no sheet await studio.toggleImmersive() // enter or leave WebXR specifically await studio.openRoom() // returns the room code studio.destroy() // releases camera, socket and GPU context

Events

studio.on(name, fn) returns an unsubscribe function. The same events also fire as ar-studio: DOM events on the mounted element.

Web component

<ar-studio

assets="https://cdn.acme.com/models.json" title="Acme AR" accent="#00b894" generate="true" rooms="true"

element.studio is the live instance. Importing 3d-ar-studio/auto (what the CDN bundle does) registers the element for you.

Keyboard and accessib