Common Settings
This guide explains the settings that appear on more than one 3D Bits surface in the Shopify theme editor. Read it alongside the page for the specific block you are configuring: the block pages cover what is unique to each one, this page covers what they share.
Overview
The 3D Bits app ships six theme app extension surfaces. Here is how each one is labelled in the theme editor:
| Shown in the theme editor as | What it is |
|---|---|
| 3D Bits - Auto 3D on product pages | The app embed. You switch it on once under App embeds and it renders every published project on its own products. This is the recommended route. |
| BITBYBIT VIEWER | Renders a project's 3D view in a spot you choose inside a product template. |
| BITBYBIT GUI CONTROLS | Hosts one area of the option panel wherever you drop it. Pairs with a viewer block or the app embed on the same template. |
| BITBYBIT PREVIEW | Embeds a public project from bitbybit.dev in an iframe. |
| BITBYBIT RUNNER (legacy) | Runs an exported script directly in the template. It keeps working for existing setups, but it is no longer the recommended path. |
| BITBYBIT APPS | Runs an entire application of your own on the product page. Pro plan only. |
The app embed covers the large majority of setups, and everything you would otherwise set here is authored in the app instead. See Theme Blocks for when placing blocks by hand is actually worth it.
Many settings below are shared across these surfaces, which is why they are documented once here rather than repeated on every block page.
Dynamic vs. Global Settings
3D Bits settings reach the storefront by three different routes, and it is worth knowing which one you are looking at before you change anything.
Product-Specific Settings (Dynamic)
Theme block settings that hold text or a colour can point at a product metafield instead of a fixed value. The block then renders a different value on every product that uses the same template, which is useful when products need different models, scenes, camera angles or backgrounds.
The app's own metafield definitions cover the settings this is usually done for:
- VIEWER: Model URL, Scene JSON Configuration, Camera Position, Camera Target, Background Color
- RUNNER: Inline Script, Public Script URL, Execute JavaScript, Fonts to include, Camera Position, Camera Target, Background Color
- PREVIEW: Model Preview URL
- APPS: Public Script URL
When you publish a Composer project, the app writes the model and scene settings onto every linked product for you. The manual metafield route below is for setups you are wiring yourself, or for a value the app does not publish.
Global Settings
Most settings are global: you set them once on the block, in the theme editor, and they apply to every product that uses that template. That is the usual choice for everything not listed above, and the matrix shows which block carries which.
The third route is the one that catches people out: for the app embed, most of these are decided by the project in the app, and whatever you type in the theme editor is ignored. See Settings the Project Overrides.
How to Link Settings to Metafields
To point a setting at a product metafield:
- Clear any default value from the setting field if one is present
- Click the cylinder icon on the right side of the setting
- Search for your metafield in the dropdown that appears

The search bar shows the product metafields available to your store: the 3D Bits ones, once they exist, and any you defined yourself. The app creates its definitions for you, as Metafields explains.
Once a setting is linked, you manage that value per product in Shopify's product editor rather than in the theme editor.
Settings by Block
This image shows where block settings live for the BITBYBIT VIEWER block. The other placed blocks keep them in the same place. The app embed is different: it lives under App embeds at the bottom of the theme editor's sidebar, not inside a template.

Here is the whole matrix. means the block has the setting and that it does not. means the setting is present in the theme editor but a published project decides the value instead.
| Setting | App embed | Viewer | GUI Controls | Preview | Runner | Apps |
|---|---|---|---|---|---|---|
| Placement (CSS selector) | ||||||
| Show Fullscreen Button | ||||||
| Show Spinner | ||||||
| Receive Input Names As Variants | ||||||
| Input Collection Mode | ||||||
| Runner CDN Link | ||||||
| Enable OCCT | ||||||
| Enable JSCAD | ||||||
| Enable Manifold | ||||||
| Model URL | ||||||
| Scene JSON Configuration | ||||||
| Camera Position | ||||||
| Camera Target | ||||||
| Background Color | ||||||
| Theme buy buttons | ||||||
| Enable Debug Mode | ||||||
| Try to Prepend | ||||||
| Prepend With Query Selector | ||||||
| Remove Children Before Prepend | ||||||
| GUI area | ||||||
| Custom area id (optional) | ||||||
| Model Preview URL | ||||||
| Inline Script | ||||||
| Public Script URL | ||||||
| Execute JavaScript | ||||||
| Enable Key Event Listeners | ||||||
| Fonts to include | ||||||
| Disable Inputs When Computing |
The App Embed
The app embed has nine settings, and only two of them are live for a project published by the current version of the app:
- Placement (CSS selector) - where the 3D view is inserted on each product page. Documented on the App Embed page.
- Runner CDN Link - which version of the runner and its assets load.
The other seven are described in Settings the Project Overrides.
The embed also does two things you cannot switch off from the theme editor. It always relocates the canvas to the placement selector, and it never hides the content already sitting there, so there is no Try to Prepend or Remove Children Before Prepend to set.
Settings the Project Overrides
This is the single most common source of confusion, so it is worth stating plainly.
When the app embed renders a product, it reads the display settings that were published with that product's project and uses those. It falls back to the block setting only when the project has not published a value - and a project published by the current version of the app always publishes all of them. In practice these seven app embed settings do nothing:
- Show Fullscreen Button
- Show Spinner
- Receive Input Names As Variants
- Input Collection Mode
- Enable OCCT
- Enable JSCAD
- Enable Manifold
Change them in the app instead. Open the project and find the Storefront settings card, and open its Storefront behaviour row. The first four are there, as Show fullscreen button, Show loading spinner, Receive input names as variants and Input collection mode, alongside Debug mode, which the app embed has no theme setting for at all. The three CAD kernels are only for a script project, which has them in a CAD kernels card on its own page, because they are the kernels that project's script needs.
Saving Storefront settings pushes the change straight out to the products already linked to that project. You do not need to publish again for it. A project that has never been published has nothing on its products yet, so publish it once first.
None of this applies to the placed blocks. A BITBYBIT VIEWER, PREVIEW, RUNNER or APPS block reads these settings from the theme editor and nothing overrides them.
Setting Details
Runner CDN Link
Available in: app embed, VIEWER, RUNNER
Default: https://git-cdn.bitbybit.dev/v1.7.0
Specifies the CDN location from which the Bitbybit runner and all its assets (workers, WASM files, BabylonJS scripts, fonts, and so on) are loaded. The runner is the core engine that loads and renders 3D content in the browser.
A project's Storefront settings do not change this field, so if you are on the embed this is still the field to edit. One thing can take its place: a configurator updated from its project page loads the runner version set there, wherever this field is empty or holds 3D Bits' own link to a release. A link to your own CDN, or to one runner file, is always used as saved. See Updating one configurator from the app.
Accepted Formats:
This field accepts two types of value:
- Base URL (recommended): a URL pointing to the root of the assets folder, for example https://git-cdn.bitbybit.dev/v1.7.0 or https://cdn.yourcompany.com/bitbybit/v1.7.0/. The runner script path (
runner/bitbybit-runner-babylonjs.js) is appended automatically. A trailing slash is optional. Everything then loads from there: the runner script, the web workers (OCCT, JSCAD, Manifold), the WASM binaries and the fonts. - Full JS URL (legacy, backward-compatible): a direct URL to the runner JavaScript file, for example https://git-cdn.bitbybit.dev/v1.7.0/runner/bitbybit-runner-babylonjs.js. The rest of the assets come from the folder it sits in, as long as it follows the standard
runner/path.
Either way the link must start with https:// or http://. Anything else - a link starting with //, for example - is ignored, and the default above is used.
The Lighter Viewer Runner:
A configurator without scripts does not need the scripting engine or the CAD kernels, so it can load a lighter viewer runner (runner/bitbybit-runner-viewer-babylonjs.js) - the same 3D rendering at less than half the download. The app embed and the VIEWER block pick it automatically when all of these are true:
- The runner link is empty, or a base URL on
https://git-cdn.bitbybit.dev/v...at a runner release that ships the viewer runner. The default link above does. Links pinned to an earlier release,latestand self-hosted links keep the full runner. - The product was published again after the app update that added the viewer runner. Publishing is when the app checks that the configurator has no scripts, so a product that has not been republished keeps the full runner.
- The block shows the product's published configurator. A scene config pasted into a VIEWER block keeps the full runner.
A disabled script does not count, because nothing runs it. If a configurator gains a script after it was published, the storefront notices the script and loads the full runner on its own; publish again so the page asks for the right runner from the start.
To force the full runner on one block, paste the full runner's .js URL into this field, for example https://git-cdn.bitbybit.dev/v1.7.0/runner/bitbybit-runner-babylonjs.js. You can see which runner a page asked for in its source: the runner's script tag carries data-bb-runner-kind="viewer" or "full". The RUNNER block runs scripts, so it always loads the full runner.
When to Change:
Update this setting when you need features from a newer version of Bitbybit, when working with scripts created in a specific version of the bitbybit.dev editor, when you need to roll back to a previous version for compatibility, or when you want to host assets on your own CDN.
A saved link stays on its version until you change it, which keeps your live configurators stable: a new runner can change how your configurator talks to the underlying 3D engine, and you want to find that out on a copy.
Safe Migration Workflow:
- Duplicate your product that contains the configurator and set it to Draft status
- Create a duplicate of the product template and configure it to use the latest runner version
- Link the duplicated template to your Draft product
- Test thoroughly to ensure your configurator works as expected
- Deploy to production once testing confirms everything functions correctly
The app embed's link applies to the whole theme rather than one template, so for the embed, try the change on a duplicate of your theme instead.
Troubleshooting After Updates:
For the app embed and BITBYBIT VIEWER: open the project in Composer, fix what it shows you, and publish again.
For BITBYBIT RUNNER: open your scripts in the bitbybit.dev editors, which bring a saved script up to date, and address any errors caused by API changes. Scripts that reach deep into the game engine may need adjusting by hand.
Self-Hosting Assets on Your Own CDN:
Hosting the assets yourself keeps your configurators independent of the Bitbybit CDN, lets you choose a CDN for your shoppers' regions and pins versions on your own schedule. Download them from the Bitbybit Assets Releases on GitHub, upload them preserving the folder structure, and set this link to your CDN's base URL. Hosting Bitbybit Assets on Your Own CDN is the full guide.
If the runner script does not load from your link, the 3D Bits app tries the default link that shipped with it. That is a safety net, not a strategy.
Check the runner docs to learn more about how the runner works.
Visit Find Release Info on our GitHub to know which runner version is the latest.
Camera Position
Available in: VIEWER, RUNNER
Default: [3, 1, 3] (VIEWER), [30, 10, 30] (RUNNER)
Where the 3D camera sits in the scene, which decides the first view of your content. Provide three numbers in the format [x, y, z], where y is up. Anything else, including an empty field, leaves the camera at [0, 10, 20].
For the VIEWER block, a camera defined in a scene configuration takes precedence over this setting. You can create and manage scene configurations using Composer.
The app embed has no camera settings at all, for the same reason: every project it renders carries its own scene, and the scene owns the camera.
Default Values Explained:
- VIEWER
[3, 1, 3]: closer view, suitable for prepared 3D models - RUNNER
[30, 10, 30]: further back, because parametric geometry often spans a larger area
Finding the Right Position:
Start with the default for your block, then adjust it to your content's size and orientation, together with Camera Target.
Larger values move the camera further from the origin (0, 0, 0). If your content appears too small or too large, adjust the distance by scaling all three values proportionally.
In the RUNNER block, your scripts can also move the camera themselves, for instance to frame geometry whose size changes.
Camera Target
Available in: VIEWER, RUNNER
Default: [0, 0, 0] (VIEWER), [0, 15, 0] (RUNNER)
The point in the scene that the camera looks at, in the same [x, y, z] format. Together, Camera Position says where the camera is, and this says what it looks at. As with the position, a camera defined in a scene configuration takes precedence.
Default Values Explained:
- VIEWER
[0, 0, 0]: looking at the origin, where models are typically centred - RUNNER
[0, 15, 0]: a point above the origin, suitable for parametric objects that extend vertically
If your model is not centred at the origin, point the target at its centre. You can find the centre coordinates by loading the model in 3D software like Blender.
Background Color
Available in: VIEWER, RUNNER
Default: #ffffff (white)
The colour of the 3D canvas behind your content, picked with the colour picker. Choose something that matches your theme and contrasts with your content. Neutral backgrounds such as white and light grey work best, because they do not distract from the model.
For the VIEWER block, this setting is ignored as soon as there is a scene configuration, whose background can be a colour, a gradient, an image or a skybox. You can configure these using Composer. The app embed has no background setting for the same reason.
Public Script URL
Available in: RUNNER, APPS
Default: Empty
Controls which script or application the block loads from an external source.
For the RUNNER block: loads a parametric script exported from the bitbybit.dev editors. An Inline Script takes precedence over it.
For the APPS block: controls the three-mode development workflow. When empty, the block embeds https://localhost:4242 for local development.
Format:
Provide a fully qualified URL to your file:
https://example.com/scripts/my-file.txt
https://localhost:4242/assets/index-stable.js
https://cdn.shopify.com/s/files/1/xxx/index-hash.js
File Requirements:
- Publicly accessible (no authentication required)
- CORS-enabled if hosted on a different domain
- RUNNER: a text file, exported from bitbybit.dev
- APPS: an ES module JavaScript file, on an
https://address
Hosting Options:
- Shopify CDN - upload under Content then Files (recommended for production)
- The app's Assets library - upload in the 3D Bits admin and copy the URL
- Local Development - localhost:4242 (APPS only)
- Cloud storage, CDN services or your own server - any HTTPS server that sends CORS headers
CORS Requirements:
If hosting on a different domain, make sure the response carries proper CORS headers:
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type
Block-Specific Usage:
For detailed usage instructions specific to each block, see:
- RUNNER: Public Script URL setting - script loading and priority
- APPS: Public Script URL setting - development modes and workflow
If you are writing parametric scripts for a store today, add them under Scripts in the 3D Bits admin and link them into a Composer project. You get the option panel, pricing and publishing around them, and you never paste a URL into a theme block. See Scripting.
Show Fullscreen Button
Available in: app embed, VIEWER, RUNNER, PREVIEW, APPS
Default: true
Controls whether the fullscreen toggle button appears on the canvas. When enabled, shoppers can click the button to enter and leave fullscreen. Disable it if your theme handles fullscreen differently.
The embed's copy of this setting is overridden by the project. Change Show fullscreen button in the project's Storefront settings instead - see Settings the Project Overrides.
Technical Note: the button uses the browser's Fullscreen API where the browser offers it. Where it does not, or where it refuses the request, 3D Bits falls back to a full-window CSS mode that looks the same to the shopper, and the Escape key leaves that mode. The PREVIEW block is the exception: it calls the Fullscreen API directly with no fallback, so on a browser without the API its button does nothing.
Show Spinner
Available in: app embed, VIEWER, RUNNER, APPS
Default: true
Controls whether a loading indicator appears while 3D content is loading or computing. Keep it on, unless you have a loading indicator of your own.
When it appears:
- App embed and VIEWER: while the scene configuration and models load, until a scene's loading screen takes its place
- RUNNER: during script execution and geometry generation
- APPS: while your application starts, and each time it receives new inputs
Change Show loading spinner in the project's Storefront settings - see Settings the Project Overrides.
If a Composer project runs scripts, the Scripting tab has a separate While computing section with its own Show spinner toggle, an indicator delay so fast scripts never flicker the page, and an input debounce. Those apply to script runs specifically.
Receive Input Names As Variants
Available in: app embed, VIEWER, RUNNER, APPS
Default: true
Determines what 3D Bits calls each input it reads from the theme's own product form.
Options:
- On (recommended): uses the input element's
nameattribute, falling back to itsid - Off: uses the text of the
<legend>inside the input's immediate parent, if there is one, and falls back tonameoridif there is not
Technical names are more reliable, because they do not change when you update display text, are not affected by translations, and stay consistent across theme updates.
What "off" actually reads:
This is worth being precise about, because it is easy to assume the setting picks up whatever label is next to the field. It does not. It looks for a <legend> element inside the input's immediate parent - the pattern Shopify themes use for grouped variant radios:
<fieldset class="product-form__input">
<legend class="form__label">Boat length</legend>
<input type="radio" name="Length" value="20 m" checked>
<input type="radio" name="Length" value="25 m">
</fieldset>
With the setting on, that group is reported as Length = 20 m. With it off, it is reported as Boat length = 20 m.
A <label> element is never used, and a field with no <legend> in its immediate parent falls back to the technical name either way - so turning this off on a theme that does not use fieldsets changes nothing at all.
Recommendation: keep it on unless a theme's legends are genuinely more stable than its input names.
Change Receive input names as variants in the project's Storefront settings - see Settings the Project Overrides.
This setting affects inputs 3D Bits reads from your theme. Controls that 3D Bits renders itself already carry a stable key you chose in Composer, and are unaffected.
Dynamic IDs in Input Names
Many Shopify themes decorate input names and ids with a section id that changes whenever the theme is edited or the section is duplicated. For example:
<select id="product-form-template--15940235894834__main" name="Length"></select>
<input id="field-abc123XYZ-boat-name" type="text">
Pin those down with a {{id}} placeholder rather than typing the id you happen to see today.
In a control's Selector field (Composer, Controls), write the placeholder in place of the changing part, inside an #id or an [attribute="value"]:
#product-form-template--{{id}}__main
input[name="option-{{id}}-size"]
[data-variant-id="{{id}}"]
Behind the scenes the placeholder becomes a "starts with" and "ends with" match on that attribute, so the first example looks for an element whose id begins with product-form-template-- and ends with __main.
In a selector, the name inside the braces is yours to choose - {{id}}, {{sectionId}} and {{section_id}} all behave identically. Single braces such as {id} are not a placeholder and are treated as literal text.
A placeholder selector is only used when it resolves to exactly one element on the page. If two elements match - two sections of the same type on one template is the usual cause - the control finds nothing rather than guessing. Narrow the selector with a container, for example .product-form #field-{{id}}-boat-name.
In a condition's input name (Logic, and the conditions on controls and options), write exactly {{id}}. It is matched against the names 3D Bits actually collected from the page, ignoring case. That is a different job from a selector, so the uniqueness rule above does not apply there - but a pattern loose enough to match several collected names is still worth tightening, because you cannot tell which one it settled on.
Publishing is blocked, not warned, if a {{id}} placeholder appears in a condition that gates a price: on a priced control or option, in a price formula, or in a part's Included when. Conditions that decide money has the message and the fix, which is to reference the control's stable key instead.
Placeholders remain perfectly fine anywhere money is not involved.
Use Enable Debug Mode to see the actual input names on your product page and work out which part of them changes.
Theme and App Updates
When you update your Shopify theme or a third-party option app, the input field names may change. That breaks any configuration matching on those names, and it can happen on a live page without notice.
Before you publish a new theme or update an app:
- Try it somewhere safe: in Shopify's theme preview for a new theme, or on a Draft duplicate of the product for an app
- Turn on Debug Mode and read the new field names in the debug panel
- Update your configuration in Composer: change each external control's Selector, which leaves its key and everything built on it alone. In a project with no controls, Edit variants renames the variants and their values in every condition
- Test all the options on the preview or the Draft product
- Turn Debug Mode off, then publish the theme or apply the change to your live products
For a configurator that matters, have 3D Bits render the controls itself, so the keys are yours and nothing external can rename them. Failing that, use established themes that keep their input names across updates, avoid apps that change their markup often, and write down the names you rely on.
If you are building product forms or Shopify apps of your own, Driving 3D Bits from Your Own Form covers input naming, values and event handling.
Input Collection Mode
Available in: app embed, VIEWER, RUNNER, APPS
Default: standard
Controls which of the page's inputs 3D Bits reads and watches for changes.
Options:
- Standard Inputs: a fixed list of input types - radio, range, text, number, checkbox, colour, email, tel, url, date, time, datetime-local, month, week and file, plus every
<select>and<textarea> - All Inputs: every
<input>,<select>and<textarea>on the page, whatever the type
It is a natural assumption that Standard only looks inside the add-to-cart form. It does not. Both modes scan the whole page, including inside open shadow roots, which is what lets 3D Bits work with themes and option apps that use web components. The difference between the modes is only which input types are included.
What Standard leaves out is the machinery: hidden inputs, submit and button inputs, search boxes and any other type not in the list above. That is usually what you want, because those carry no shopper choice.
Standard is the right choice for most setups. Use All Inputs for a form builder that keeps its state in hidden inputs, or a page with non-standard input elements. It can cost more on pages with a great many inputs.
All Inputs picks up unrelated fields too - newsletter signups, search boxes, and any hidden field your theme uses for its own bookkeeping. Use Enable Debug Mode to check exactly what is being collected before you rely on it.
Change Input collection mode in the project's Storefront settings - see Settings the Project Overrides.
Future Compatibility
Support for particular third-party option apps lives in the debug panel rather than in this dropdown. Open Debug Mode, switch to the GUI Setup tab, and pick a Scraper Profile. The generic profile reads a plain product form; Easify Product Options understands that app's markup and produces cleaner controls from it. The panel then hands you the result as JSON to import into Composer.
Enable Debug Mode
Available in: VIEWER, RUNNER, APPS (on the app embed, it is a project setting)
Default: false
Shows a panel on the product page listing every input 3D Bits reads. It is the tool for integrating a third-party option app or a form of your own.
What the panel contains depends on which block drew it.
On the BITBYBIT VIEWER block and the app embed, which share the same runtime, the panel has two tabs:
- Live - a table of every option name and value 3D Bits is currently collecting, with a Copy button on each. This is where you find out what your theme actually calls a field.
- GUI Setup - scrapes the page's forms into ready-made 3D Bits controls, which you can edit inline and then take away with Copy JSON or Download. A Scraper Profile picker adapts the scrape to a known option app, and Refresh re-reads the page.


The GUI Setup tab says so itself: the titles it invents are guesses from your markup. Rename them to your own option names before you rely on them.
On the BITBYBIT RUNNER and BITBYBIT APPS blocks there are no tabs. The panel prints the inputs as raw JSON in the same place on the page - the RUNNER prints the collected inputs, the APPS block prints the collected inputs together with the block's settings. It still answers the question the Live tab answers, which is what your theme calls each field, but there is no per-row button, no scraper and no GUI Setup tab. The app embed draws the same raw JSON for a script project.
The app embed has no debug setting in the theme editor. Turn Debug mode on and off in the project's Storefront settings and save - see Settings the Project Overrides.
When to Use
Enable debug mode when you are setting up a new block or project, working out why option matching does not work, finding field names, including dynamic ids, comparing the Input Collection Mode settings, or building a first set of controls from an existing form. Support may also ask you to turn it on for a while.
Example Debug Output
The Live tab lists names on the left and values on the right, which corresponds to a set of inputs like this, with a number read as a number:
{
"Length": "20 m",
"Helm": "Sport",
"tender": true,
"quantity": 1
}
Usage Workflow
- Enable debug mode - in the theme block for a placed block, or in the project's Storefront settings for the app embed
- Visit your product page
- Note the input field names and values on the Live tab
- Use those names in your configuration, or build controls from the GUI Setup tab
- Disable debug mode when you are done
Always disable debug mode before your changes go live. The panel is visible to every visitor and reveals technical details about your page structure.
Try to Prepend
Available in: VIEWER, RUNNER, PREVIEW, APPS (no effect on APPS)
Default: false
Moves the 3D canvas to a different place on the page, chosen with a CSS selector. With it off, the canvas stays where you placed the block. The usual reason is to show 3D in the product media gallery, beside or in place of the photos, without editing theme code.
How it works:
When enabled, the block looks for the element named in Prepend With Query Selector and inserts the canvas as that element's first child. If your selector matches nothing, the block does not wait for it: it falls straight back to the theme's add to cart form, form[action*="/cart/add"], and puts the canvas at the top of the section that holds it, so a mistyped selector leaves the canvas in the default place rather than nowhere. Only when there is no cart form either - a situation you get on themes that build the whole page in JavaScript - does it retry, once a second, up to ten times, before giving up and logging a warning to the browser console.
The PREVIEW block is the exception: it looks once, as the page loads, and does not retry or fall back. If your selector points at something a script creates later, PREVIEW will miss it.
Different themes need different selectors, so check your theme's markup.
The APPS block lists this setting and the two below it, but they do not move it. Position an APPS block by where you place it.
The app embed always relocates the canvas, so it has no on/off switch. It has a single Placement (CSS selector) field instead, defaulting to the add-to-cart form rather than a gallery class, because every theme has one.
Prepend With Query Selector
Available in: VIEWER, RUNNER, PREVIEW, APPS (no effect on APPS)
Default: div.product__media-wrapper
The CSS selector for the target element when Try to Prepend is enabled.
What is a Query Selector?
A query selector is a pattern that identifies an HTML element on your page, in the same syntax as CSS stylesheets. The default, div.product__media-wrapper, targets a <div> with the class product__media-wrapper, which is the product image area in Shopify's Dawn theme. Other themes use other names.
Common Selectors
/* By class name */
.product-images /* Element with class="product-images" */
div.gallery /* div with class="gallery" */
/* By ID */
#product-media /* Element with id="product-media" */
/* By tag and class */
section.product-main /* section with class="product-main" */
/* More specific */
.product .media-gallery /* .media-gallery inside .product */
Finding the Right Selector
- Open browser developer tools (F12 or right-click → Inspect)
- Find the element you want to target in the Elements/Inspector tab
- Look for the element's class or id in the HTML
- Test your selector in the browser console:
The first element it returns is the one the canvas will move into.document.querySelectorAll('your-selector-here')
Best Practices
- Be specific enough that the first match is the element you meant - if the selector matches several, the first one on the page wins, silently
- Prefer classes over ids when a theme generates ids that change
- Test on multiple products to ensure consistency
- Avoid overly complex selectors that might break with theme updates
The prepend selector is a plain CSS selector, so the {{id}} placeholder from Dynamic IDs in Input Names does not work here. Give it a class or a container instead.
Remove Children Before Prepend
Available in: VIEWER, RUNNER, PREVIEW, APPS (no effect on APPS)
Default: false
When enabled, hides the content already inside the target element, so the 3D canvas stands alone there. Use it to show 3D in place of the product images. With it off, the canvas appears first and the photos stay below it.
Shoppers then no longer see the standard product images in that container, so consider what a visitor sees if the 3D fails to load, and test before enabling it on a live store.
On the VIEWER and RUNNER blocks the existing children are hidden with CSS rather than removed from the page, and only the ones present at the moment the canvas is moved in. Anything your theme adds to that container afterwards - a gallery that populates late, for instance - is not hidden. If the result looks wrong, that is usually why.
The PREVIEW block is the exception: it removes children from the page outright, and only a page reload brings them back. When the element has several, it can miss some, so check the page.
Typical workflow:
- Enable Try to Prepend
- Set Prepend With Query Selector to the target container
- Enable this setting to hide the existing images
- The canvas becomes the visible content in that container
If your selector falls back to the add to cart form, nothing is hidden: the theme's form is never touched.
Disable Inputs When Computing
Available in: RUNNER, APPS
Default: false
Disables the page's inputs, and every button on it, while a script or application is processing. It stops shoppers stacking changes on top of a slow run.
They become visually disabled and shoppers cannot use them, then come back on their own when processing completes. It works alongside Show Spinner. The inputs it covers are the ones Input Collection Mode reads.
Use it for slow scripts, or where rapid changes cause problems. Leave it off for fast scripts and simple products, where it only makes the page feel slower.
Technical Note: this appears only on the RUNNER and APPS blocks, which run code supplied through the theme editor. It is not that a Composer project cannot do the same - it can. A project that runs scripts has its own Disable inputs toggle on Composer's Scripting tab, next to an indicator delay so short computations never lock the form at all. The PREVIEW block runs nothing of yours, so it has neither.
Theme buy buttons
Available in: VIEWER
Default: Auto (recommended)
Decides how much of the theme's own buying interface gets out of the way when 3D Bits is doing that job instead.
| Option | What it hides |
|---|---|
| Auto (recommended) | Hides the theme's add-to-cart button, its quantity and its accelerated checkout buttons when your configuration renders its own add-to-cart. Hides only the accelerated checkout buttons when the configuration saves data onto the order. Otherwise hides nothing. |
| Always hide | Hides the theme's add-to-cart, quantity and accelerated checkout buttons, whatever the configuration does. |
| Hide all product option controls | The above, plus the theme's variant pickers, for a page where 3D Bits owns every choice. |
| Never hide | Leaves the theme entirely alone. |
The cart form itself stays intact underneath in every mode, so the theme keeps working. If the only add-to-cart in your configuration is hidden on the shopper's screen, the theme's own button stays, so they can always buy.
On the block it is Theme buy buttons. The same setting in a project's Storefront settings is called Theme product controls, and its four choices are worded differently: Smart - hide what the configurator replaces (recommended), Hide buy buttons and quantity, Hide default product details and Show everything, in that order. They map one-for-one onto the four above, with one addition: with the app embed's Split layout, Hide default product details also hides the theme's product column that otherwise stays under the 3D view, title and price included, unless your GUI sits in it.
Shop Pay, Apple Pay and the other express buttons skip the line item properties that carry a configuration onto the order. If a shopper used them, you would receive an order with no record of what they configured. That is why Auto removes them as soon as your configuration writes order data, even when the theme's ordinary add-to-cart button is still the one being used.
The app embed applies exactly the same rule from the project's own settings, so there is nothing to set for it here. A paused configurator hides all of it, whatever this says. There is more on when to move off Auto on the BITBYBIT VIEWER settings page.
GUI area
Available in: GUI CONTROLS
Chooses which area of the option panel this block hosts. Elements are assigned to areas in Composer, on the Layout tab, and each GUI CONTROLS block claims one of them and renders it wherever you have placed the block in the template.
The dropdown offers ten areas: Main panel (all unassigned elements), the four canvas corners, the four canvas edges and Buy area.
The canvas centre is the one built-in area the dropdown does not list. If you assigned elements to it in Composer, type canvas-center into Custom area id instead.
Full detail is on the BITBYBIT GUI CONTROLS page.
Custom area id
Available in: GUI CONTROLS
Default: Empty
Overrides the GUI area dropdown with an area id you authored yourself in Composer, for example area_x1. Leave it empty to use the dropdown.
Anything typed here wins over the dropdown selection, so clear it if you go back to a built-in area.
Best Practices
During development, enable Debug Mode to see what 3D Bits reads, test Try to Prepend with different selectors, and compare both Input Collection Mode settings on the Live tab.
In production, always disable Debug Mode, and keep Show Spinner and Receive Input Names As Variants on.
When moving the canvas, test on several product pages and on mobile, think through Remove Children Before Prepend, and write your selector down for later.
If you are on the app embed, consistency is handled for you: the settings come from each project, so the same project behaves the same way on every product it is linked to.
Related Documentation
For block-specific settings, see:
- App Embed
- BITBYBIT VIEWER Settings
- BITBYBIT GUI CONTROLS
- BITBYBIT RUNNER Settings
- BITBYBIT PREVIEW Settings
- BITBYBIT APPS Settings
For setup and configuration:
Support
If you need help with common settings:
- Check the FAQ
- Contact support through the Shopify app dashboard or directly at info@bitbybit.dev
- Visit bitbybit.dev for additional resources
Verified against the product in November 2026