How to Use

7 min read

Adding a model to a product

Go to Product 3D Models and open a product.
In the Model file card, either:
- Upload — pick a .glb or .gltf from your computer (or drag it in). If the product already has one, the button reads Upload (Replace).
- Choose from Files — reassign a model already in Shopify Files.
- Remove — detach the model from the product. The file stays in Shopify Files.
Adjust the Viewer settings (full reference below). The Live preview on the right re-renders as you type.
Click Save And View to save and open the live product page, or Save alone to persist without leaving.

File requirements: .glb (recommended) or .gltf. Maximum 20 MB, but keep files under ~10 MB so product pages stay fast.

Viewer settings reference

Every setting is per-model and stored as JSON in custom.viewer_3d_config.

Display

Setting	Range / options	Default	What it does
Viewer height	200–1200 px	500	Height of the viewer box on the page
Background color	any hex	`#ffffff`	Canvas background behind the model
Exposure	0–5	1	Overall brightness of the lighting
Tone mapping	None, Linear, Reinhard, Cineon, ACESFilmic	Linear	How bright values roll off. ACESFilmic looks most cinematic; Linear is truest to the source
Default environment map	on / off	on	Uses the built-in studio lighting. Turn off to supply your own
Blur skybox	on / off	off	Softens the background skybox without affecting reflections
Cast shadow under model	on / off	on	Contact shadow on the ground plane

Environment

Setting	What it does
Skybox HDR URL	HDR image used as the visible background
Environment map HDR URL	HDR image used for reflections and lighting only

Leave both empty to use the default environment. Host the .hdr files anywhere publicly reachable — Shopify Files works.

Camera

Setting	Range	Default	What it does
FOV mode	auto / custom	auto	Auto fits the model to the frame; custom lets you set the angle
FOV (degrees)	1–179	45	Field of view. Lower is more telephoto/flatter, higher is wider/more dramatic
Initial yaw	−360°–360°	0	Horizontal starting angle
Initial pitch	−90°–90°	0	Vertical starting angle — positive looks down at the model
Initial zoom	−100–100	0	Starting distance relative to the auto-fit
Maintain model size on resize	on / off	off	Keeps the model a constant on-screen size when the viewport changes

Controls

Setting	Default	What it does
Allow rotate	on	Drag to orbit the model
Allow translate (pan)	on	Right-drag / two-finger drag to move the model
Allow zoom	on	Pinch or wheel to zoom
Auto rotate	on	Model spins slowly on its own
Page scroll on touch	on	Vertical swipes scroll the page instead of being eaten by the viewer. Leave on for mobile product pages
Page scroll on mouse wheel	off	Turn on so the wheel scrolls the page rather than zooming the model
Grab cursor on canvas	on	Shows the hand cursor so visitors know it’s draggable

Control bar

The on-screen buttons overlaid on the viewer. By default only fullscreen and zoom are shown — a product-page viewer should read as a photo that turns, not as an application.

Button	Default	What it does
Animation clip name/switcher	off	Lets visitors pick which animation plays. Note: with this hidden, animation does not play at all
Axis gizmo (X/Y/Z)	off	Small orientation indicator
Zoom in / out buttons	on	Explicit zoom controls
Camera (snapshot) button	off	Downloads a PNG of the current view
Resets view	off	Returns the camera to its starting position
Fullscreen button	on	Expands the viewer to the full screen

Animation

Setting	Range	Default	What it does
Default animation index	0–99	0	Which clip in the file plays first
Repeat mode	one / all / none	one	Loop the current clip, cycle through all clips, or play once

AR

Setting	Default	What it does
WebXR AR	on	In-browser AR on modern Android Chrome
Google Scene Viewer	on	Android’s native AR viewer
Apple Quick Look	on	iOS AR — requires the `.usdz` below
iOS source URL (`.usdz`)	empty	Upload a `.usdz` separately to Shopify Files and paste its URL here. Without it, Quick Look has nothing to show

Advanced

Setting	Default	What it does
Material variant	empty	Name of a `KHR_materials_variants` variant to load by default
Fix skinned bounding box	on	For rigged models, fits the camera to the posed mesh rather than the bind pose. Without it, character models often render as a tiny speck

3D Model Library

Your central store of models, independent of any product.

Adding models

Drop a .glb / .gltf onto the drop zone, or click Upload new.
Choose from Files imports a model already in Shopify Files.

Finding models

Search by name.
Sort by Newest first, Oldest first, Name (A→Z), or Largest first.
Toggle between list and grid view.

Per-model quick actions (the icon buttons on each row)

Copy Model ID — paste into the 3D Viewer — Any Model theme block.
Copy embed code — the iframe snippet, for any page that accepts HTML.
Copy file URL — the raw .glb URL.
Delete — removes it from the library. The .glb itself stays in Shopify Files.

Bulk actions Select models with the checkboxes (or Select all), then Delete selected from the bar that appears at the top.

Model detail page Open any model to get:

Details — file name, size, and the copyable Model ID and public link.
Share & embed — the iframe snippet, with a Responsive / Fixed toggle.
Viewer settings — the same full settings panel as the product page.
Live preview — updates as you edit.
Preview and Delete buttons in the header.

Placing the viewer on your storefront

Requires an Online Store 2.0 theme with JSON templates — Dawn and most modern themes qualify.

Product pages

Online Store → Themes → Customize → Product template → Add section → Apps → 3D Viewer — Product.

Block settings:

Manual model URL — leave empty so it falls back to the product’s assigned model. Only fill this in to hard-code one specific file.
Viewer height and Background color — fallbacks used when no per-product config exists.

Add this block once and every product with a model uses it automatically.

Home page, custom pages, blog posts

Pick that template at the top of the theme editor, then Add section → Apps → 3D Viewer — Any Model.

Block settings:

Model ID — paste from the 3D Model Library. Preferred: the ID resolves through the shop library metafield, so the model’s saved viewer settings travel with it.
Model URL — a raw .glb URL instead. This brings only the file, so the block’s own height and background apply.
Caption (optional)
Viewer height, Background color, Auto rotate, Show on-screen controls

Embedding a model anywhere

Every model has a standalone public page at /viewer/<model-id>. The Share & embed card gives you a ready iframe.

Where to use it

A Shopify page or blog post — switch the rich text editor to the </> HTML view and paste.
A Custom Liquid section, anywhere in any theme, including legacy .liquid templates.
Any site outside Shopify.

Two modes

Responsive — a 4:3 box that scales to any column width.
Fixed — pins the model’s saved height.

URL overrides — so one model suits several placements without re-saving it:

?bg=101014 — sets the background to match the host page (hex, no #).
?autorotate=0 — stops it spinning.

The snippet is inline-styled with no classes and no <script>, so Shopify’s HTML sanitiser leaves it intact and your theme CSS can’t collide with it. Keep allow="fullscreen" on the iframe or the fullscreen button won’t work.

Preview vs Save

Live preview (right-hand panel) re-renders instantly as you edit. Saving only persists the change.
Preview opens the storefront with your unsaved changes applied via a URL fragment. Nothing is written.
Save And View saves first, then opens a fresh storefront tab. Shopify takes a few seconds to propagate metafield writes — the placeholder spinner is waiting for that, not stuck.

Plans

	Free	Pro — $9.99/mo	Pro Plus — $29.99/mo
Models	Up to 5	Up to 50	Unlimited
Trial	—	7 days	7 days
	Embed on product pages and pages	Everything in Free	Everything in Pro
	All viewer customization options	HDR skybox and environment maps	AR Quick Look (iOS) + Scene Viewer (Android)
	Live preview in admin	Material variants	Custom annotations
	Standard support	Priority email support	Premium support

Existing model assignments are never removed on a downgrade — only new uploads beyond the limit are blocked.

Troubleshooting

Block renders nothing. The product has no model assigned. Upload one, or paste a manual URL ending in .glb / .gltf.

Storefront ignores your saved changes. The metafield definitions are missing Storefront read access. Run Create / fix definitions on the Setup page, then hard-refresh the storefront.

Model ID reports “not found”. Run Setup — that button writes the shop library metafield the Any Model block reads.

Model appears white. The viewer is mid-initialisation because a structural option just changed (tone mapping, environment map). Wait a moment, or revert that field.

Animation doesn’t play. The clip switcher is hidden. Turn on Animation clip name/switcher under Control bar — hiding it means “no animation”, not “animation you can’t control”.

Model renders as a tiny speck. It’s a rigged model and Fix skinned bounding box is off. Turn it on.

Model spins when I try to scroll the page. Turn on Page scroll on mouse wheel (desktop) and confirm Page scroll on touch is on (mobile).

Quick Look does nothing on iPhone. iOS needs a separate .usdz. Upload one to Shopify Files and paste its URL into AR → iOS source URL.

Pop-up blocked. Save And View and Preview must be a direct click, not a programmatic trigger. Allow pop-ups for your admin domain.

Fullscreen button does nothing in an embed. The iframe is missing allow="fullscreen". Re-copy the snippet from Share & embed.

Was this page helpful?