3D Product Models
Show products as interactive 3D models that react to options: parts, colours and finishes
Show a product as an interactive 3D model that updates live as customers pick options: parts appear and disappear, colours change, and finishes go from matte to gloss before checkout.
How 3D Works in Uplift
A 3D model is a canvas layer, like an image layer. When a product has a 3D model (GLB) layer, the Canvas Display block shows a WebGL viewer instead of the 2D canvas. Customers drag to turn the model; zoom and pan are switched off so the page keeps scrolling normally.
The model reacts to selections in three ways:
| Mapping | What it does | Driven by |
|---|---|---|
| Nodes | Shows or hides parts of the model (a handle, a lid, a strap) | Any option: radio, dropdown, checkbox or swatch, or a variant option such as Size |
| Materials | Recolours a material with the selected swatch colour | Color swatch add-ons |
| Colourways | Switches between complete colourways stored in the file | Any option or variant option |
| Finish presets | Changes roughness, metalness, clearcoat or colour while an option is selected | Any option or variant option |
Pricing, linked variants, conditional logic and cart properties work exactly as they do for 2D products. The 3D layer only changes what the customer sees.
Before you start: you need a GLB file prepared for Uplift. See Preparing 3D Files for export settings, naming and size limits.
Step 1: Add the 3D Model Layer
- Open the product in Uplift
- Go to Layers & Badges and click Add Layer
- Set the layer type to 3D model (GLB)
- Upload your
.glbfile (up to 50 MB) - Wait while Shopify processes the file, then click Add Layer
During upload Uplift optimises the model for the storefront. Textures are resized and re-encoded as WebP until the file is about 2 MB. Geometry, node names and material names are left untouched. The editor shows the result, for example Optimised for the storefront: 7.5 MB → 1.1 MB (textures ≤ 1024 px).
Files still larger than 6 MB after optimisation are rejected. See Keeping files small.
Step 2: Map Options to Nodes
Open the 3D layer to see its editor. Uplift reads the file and lists every named node and material it found.
Each node has a visibility control:
- Always visible: the default. Use it for parts that never change, such as the body of the product.
- A rule: pick an option, for example Lid → Straw lid. The node stays hidden until that option is selected.
- (when checked): for checkbox add-ons. The node shows while the box is ticked.
A node can have several rules. It shows when any of them matches, so one Handle node can appear for both Add-ons → Carry handle and Bundle → Starter kit.
Rules on Shopify variant options
The product's own variant options are listed too, marked (variant): for example Size → 30 oz (variant). Use them when a part depends on the variant the customer picks rather than an Uplift add-on, such as a taller body for the 30 oz size. Variant options work the same way in colourway rules and finish presets.
Example: Tumbler lids
| Node | Rule |
|---|---|
Body | Always visible |
Lid_Slide | Lid → Slide lid |
Lid_Straw | Lid → Straw lid |
Handle | Add-ons → Carry handle |
Mark one lid option as the default in the add-on so a lid is showing when the page loads.
Step 3: Recolour Materials with Swatches
Under Materials, choose a colour source for each material you want to recolour:
- Keep model colour: the material keeps the colour from the file
- Colour from: [swatch add-on]: the material takes the hex colour of the selected swatch
One swatch add-on can drive several materials. For example, a Frame colour add-on can recolour both the temples and earhooks materials of a pair of sunglasses.
Swatch colours multiply with the material's base colour texture. For true-to-swatch colours, give recolourable materials a white or light grey base colour. See Recolourable materials.
Step 4: Map Colourways (Optional)
Some models store several complete colourways in one file (the glTF KHR_materials_variants extension), for example a sneaker in Midnight, Beach and Street. When Uplift finds them, the editor shows a Colourways section:
- Default colourway: the one shown before the customer picks an option. Model's own materials shows the file as exported.
- Add colourway rule: pick an option, then the colourway it switches to. Add one rule for each option.
Colourways suit products where one choice changes several materials or textures at once. Swatch colours and finish presets still apply on top of the active colourway. To store colourways in a file, see Built-in Colourways.
Step 5: Add Finish Presets (Optional)
Open Advanced: finish presets to change how a material looks while a specific option is selected. Each preset has:
| Field | Range | Effect |
|---|---|---|
| Roughness | 0 to 1 | 0 is mirror-smooth, 1 is fully matte |
| Metalness | 0 to 1 | 1 for metals such as steel, gold or aluminium |
| Clearcoat | 0 to 1 | A glossy lacquer layer on top, like car paint |
| CC rough. | 0 to 1 | Roughness of that clearcoat layer |
| Colour | #rgb or #rrggbb | Overrides the swatch colour while active |
Leave a field empty to keep the model's own value.
Example: Finish options on a tumbler
| Option | Material | Rough. | Metal. | Clearcoat | Colour |
|---|---|---|---|---|---|
| Finish → Gloss | BodyPaint | 0.22 | 0.08 | 1 | |
| Finish → Brushed steel | BodyPaint | 0.32 | 1 | 0 | #d9d9de |
Step 6: Adjust the Scene
| Setting | Default | Notes |
|---|---|---|
| Auto-rotate | On | Spins slowly until the customer drags the model. Always off for visitors who prefer reduced motion. |
| Environment light intensity | 1.0 | 0 to 3. Raise it for dark materials, lower it if whites look washed out. |
| Background | transparent | Any CSS colour, for example #f6f6f7. Transparent lets your theme's background show through. |
Fixed camera angle
By default the camera frames the whole model automatically. To start every customer from a particular view, such as a three-quarter angle that shows a logo:
- Turn the model to the angle you want in the Customer Preview
- Tick Fixed camera angle. Uplift copies the preview's current view.
- Fine-tune Camera position, Looks at (the point the camera faces) and Field of view if needed. The preview updates as you type.
Click Use preview angle at any time to copy a new view. Untick Fixed camera angle to go back to automatic framing. Customers can still drag the model to turn it.
Step 7: Preview and Publish
The Customer Preview in the Uplift admin renders the same 3D model with the same rules as your storefront. Click through every option and check that:
- The right parts show and hide
- Colours match the swatches
- Finishes look right under the default lighting
Save, then open the product on your storefront to confirm.
Performance
3D is designed to stay out of the way of your product page:
- Loaded late: the viewer and model load after the page has finished loading, once the canvas is near the screen and the browser is idle. Your product page's first render, text and Add to cart button are not delayed.
- No layout shift: the viewer sits on top of the canvas space, so nothing below it moves.
- Served from Shopify's CDN: models are stored in Shopify Files, so Uplift adds no hosting cost or bandwidth limit.
- Renders only when visible: rendering pauses when the viewer scrolls out of view.
- Small files: files are kept small on upload, as described in Step 1.
Fallback Behaviour
If a browser can't run WebGL, or the model fails to load, the Canvas Display shows the 2D canvas instead: your other layers and the product image. Keep a good product image on every 3D product so this fallback still looks right.
Replacing a Model
Click Replace model in the layer editor and upload the new file. Your node, material and preset mappings are kept. Any mapped name that no longer exists in the new file is marked Not in file, so you can update or remove it.
Click the refresh icon next to Replace model to re-read the names from the file.
Troubleshooting
The model doesn't appear on the storefront
- Confirm the Canvas Display block is on the product template (see Installation & Theme Setup)
- Scroll the canvas into view and wait a moment: the viewer loads once the page is idle
- Try another browser. If the 2D canvas shows instead, the browser may not support WebGL.
A part is always hidden
A node with rules stays hidden until one rule matches. Check that the add-on has a default option, or add a rule for the option that should show it.
"Not in file" next to a node or material
The name is mapped but no longer exists in the model, usually after Replace model or a re-export that renamed parts. Re-map the new name and remove the old rule.
Colours look darker than the swatch
The material's base colour texture is darker than white, and swatch colours multiply with it. See Recolourable materials.
Upload rejected as too large
The file is still above 6 MB after texture compression, so the geometry is too heavy. See Keeping files small.
Next Steps
- Preparing 3D Files: export settings, naming and size
- Color Swatches Guide: set up the swatches that drive material colours
- Conditional Logic Guide: show option groups only when they apply