Skip to main content

Driving 3D Bits from Your Own Form

Most stores build their option panel in Composer and never read this page. Composer gives you the controls, the styling, the logic and the pricing, and because those controls are ours, everything on this page is handled for you.

This page is for the other case: you have a development team, you have built or intend to build the product form yourself, and you want the 3D scene to follow it. That works well, and it comes down to one thing.

Use real form elements​

3D Bits watches the form fields on your page. When one changes, it reads the field's name and value and hands them to your configuration, which decides what the 3D scene should show. So anything the customer can choose has to exist as an actual form field.

This is not an arbitrary requirement, and meeting it does you other favours. Real form elements give you keyboard navigation, screen reader support and semantic meaning for free, so a form that works with 3D Bits is also a form that works for people using assistive technology.

Consider the difference between these two approaches:

❌ Poor Practice - Custom Div Elements​

<!-- This won't work with 3D Bits and breaks accessibility -->
<div className="custom-option" onclick="selectColor('red')" data-value="red">
  <img src="red-swatch.jpg" alt="Red color">
  <span>Red</span>
</div>
<div className="custom-option" onclick="selectColor('blue')" data-value="blue">
  <img src="blue-swatch.jpg" alt="Blue color">
  <span>Blue</span>
</div>

✅ Good Practice - Standard Radio Buttons​

<!-- This works perfectly with 3D Bits and is accessible -->
<fieldset>
  <legend>Choose Color</legend>
  <label>
    <input type="radio" name="color" value="red" checked />
    <img src="red-swatch.jpg" alt="Red color option" />
    Red
  </label>
  <label>
    <input type="radio" name="color" value="blue" />
    <img src="blue-swatch.jpg" alt="Blue color option" />
    Blue
  </label>
</fieldset>

Essential HTML Patterns for 3D Bits​

Radio Buttons for Single Selections​

When users need to choose one option from multiple choices (like material, color, or size), radio buttons are your best friend. The name attribute groups related options together, while the value attribute tells 3D Bits which option is selected.

<fieldset>
  <legend>Material Selection</legend>
  <label>
    <input type="radio" name="material" value="wood" checked />
    Natural Wood
  </label>
  <label>
    <input type="radio" name="material" value="metal" />
    Brushed Steel
  </label>
  <label>
    <input type="radio" name="material" value="plastic" />
    Recycled Plastic
  </label>
</fieldset>

Checkboxes for Multiple Selections​

For features that can be independently enabled or disabled (like add-ons or accessories), checkboxes provide the perfect solution. The value attribute determines what gets sent to 3D Bits when the checkbox is checked, while the checked attribute sets the initial state.

<fieldset>
  <legend>Additional Features</legend>
  <label>
    <input type="checkbox" name="led_lighting" value="enabled" checked />
    LED Lighting System
  </label>
  <label>
    <input type="checkbox" name="wireless_charging" value="enabled" />
    Wireless Charging Pad
  </label>
  <label>
    <input type="checkbox" name="premium_finish" value="enabled" />
    Premium Finish Coating
  </label>
</fieldset>
Checkbox Values Explained
  • value="enabled": When checked, 3D Bits receives "enabled" as the value
  • checked: Makes the checkbox selected by default when the page loads
  • When unchecked, no value is sent (which 3D Bits interprets as the feature being disabled)

Alternatively, you might want to use boolean values or specific identifiers:

<fieldset>
  <legend>Optional Accessories</legend>
  <label>
    <input type="checkbox" name="leather_seats" value="leather" />
    Leather Seats
  </label>
  <label>
    <input type="checkbox" name="sunroof" value="panoramic" />
    Panoramic Sunroof
  </label>
</fieldset>

Select Dropdowns for Space-Efficient Options​

When you have many options but limited screen space, select elements provide a clean, accessible solution.

<label for="size-selector">Product Size</label>
<select name="size" id="size-selector">
  <option value="small">Small (10cm)</option>
  <option value="medium" selected>Medium (15cm)</option>
  <option value="large">Large (20cm)</option>
  <option value="extra-large">Extra Large (25cm)</option>
</select>

Range Inputs for Continuous Values​

For dimensions, quantities, or other numeric values that users can adjust within a range, the range input provides an intuitive interface.

<label for="height-slider">Height: <span id="height-value">50</span>cm</label>
<input 
  type="range" 
  name="height" 
  id="height-slider"
  min="30" 
  max="100" 
  value="50"
  oninput="document.getElementById('height-value').textContent = this.value" />

Number Inputs for Precise Values​

When users need to enter specific numeric values, number inputs provide validation and appropriate keyboard interfaces on mobile devices.

<label for="quantity">Quantity</label>
<input 
  type="number" 
  name="quantity" 
  id="quantity"
  min="1" 
  max="100" 
  value="1" />

Critical Attributes for Success​

The name attribute is absolutely crucial for 3D Bits integration. This attribute identifies which form field controls which aspect of your 3D model. Make sure your name attributes are:

  • Descriptive: Use names like material, color, or size rather than generic names like option1 or field2
  • Consistent: If you have multiple products, use the same naming convention across all forms
  • Unique: Each form control should have a unique name within its form context
Avoid Duplicate Input Names

If you have multiple inputs with the same name attribute on the same page, 3D Bits may have difficulty determining which one to monitor. When this happens, 3D Bits will automatically add suffixes to distinguish between them, which can make your configuration more complex and harder to maintain. Always ensure input names are unique across your entire page.

For example, avoid patterns like this:

<!-- DON'T DO THIS - Duplicate names cause confusion -->
<div className="product-1">
  <input type="radio" name="color" value="red" />
  <input type="radio" name="color" value="blue" />
</div>
<div className="product-2">
  <input type="radio" name="color" value="red" />
  <input type="radio" name="color" value="blue" />
</div>

Instead, use unique, descriptive names:

<!-- DO THIS - Unique names are clear and reliable -->
<div className="product-1">
  <input type="radio" name="product1_color" value="red" />
  <input type="radio" name="product1_color" value="blue" />
</div>
<div className="product-2">
  <input type="radio" name="product2_color" value="red" />
  <input type="radio" name="product2_color" value="blue" />
</div>
Pro Tip

Always test your forms with keyboard navigation (Tab key) and screen readers to ensure they work for all users. If you can't navigate your form without a mouse, neither can users who rely on assistive technologies.

What Breaks the Integration​

Certain HTML patterns will prevent 3D Bits from detecting user selections and create barriers for users with disabilities:

Custom Clickable Divs​

<!-- Don't do this -->
<div className="option" onclick="changeOption('blue')">Blue Option</div>

This approach fails because:

  • 3D Bits can't detect the selection change automatically
  • Screen readers don't announce it as a selectable option
  • Keyboard users can't navigate to it
  • The current selection state isn't communicated to assistive technologies

Image-Only Selections Without Form Elements​

<!-- Don't do this -->
<img src="option1.jpg" onclick="selectOption(1)" class="selectable">

While visually appealing, this pattern excludes users who rely on keyboard navigation or screen readers.

JavaScript-Dependent Custom Controls​

<!-- Don't do this -->
<span className="custom-radio" data-value="option1">Custom Option</span>

Custom controls that rely entirely on JavaScript event handling often lack the semantic meaning and keyboard accessibility of native form elements.

Testing Your Integration​

To ensure your forms work correctly with 3D Bits and remain accessible:

  1. Navigate with keyboard only: Press Tab to move through all form elements. Every interactive element should be reachable and usable.

  2. Test with a screen reader: Use built-in screen readers (like VoiceOver on macOS or NVDA on Windows) to verify that options are announced clearly.

  3. Verify 3D Bits integration: Make selections in your form and confirm that the 3D model updates appropriately.

  4. Check on mobile devices: Ensure form elements display and function correctly on touch interfaces.

When Custom Solutions Are Necessary​

Last Resort Only

The approach described below should only be used when you absolutely cannot achieve your design requirements with standard HTML form elements. This pattern introduces complexity and potential accessibility issues that you'll need to carefully manage.

Sometimes your business requirements demand custom UI elements that go beyond standard form controls. In these rare cases, you can still maintain compatibility with 3D Bits and accessibility by using hidden form elements that mirror your custom interface. However, this approach comes with significant drawbacks and should be avoided whenever possible.

This pattern is problematic because it duplicates functionality, increases maintenance complexity, and can easily fall out of sync between your visual interface and the hidden form elements. Additionally, users with disabilities may miss important visual cues that aren't properly communicated to assistive technologies.

<!-- Custom visual interface -->
<div className="custom-color-picker">
  <div className="color-option red" onclick="selectColor('red')"></div>
  <div className="color-option blue" onclick="selectColor('blue')"></div>
</div>

<!-- Hidden form element for 3D Bits integration - NOT RECOMMENDED -->
<input type="hidden" name="color" id="selected-color" value="red" />

<script>
function selectColor(color) {
  // Update visual state
  document.querySelectorAll('.color-option').forEach(el => 
    el.classList.remove('selected'));
  document.querySelector('.color-option.' + color).classList.add('selected');
  
  // Update hidden form element for 3D Bits
  document.getElementById('selected-color').value = color;
  
  // Trigger change event so 3D Bits can detect the update
  document.getElementById('selected-color').dispatchEvent(new Event('change'));
}
</script>

Remember that this approach requires you to manually ensure that keyboard navigation works, screen readers can understand the interface, and the hidden form elements stay synchronized with your visual interface. Before implementing this pattern, seriously consider whether your design goals can be achieved by styling standard form elements instead.

By following these practices, you'll create forms that work seamlessly with 3D Bits while providing an excellent experience for all your users, regardless of how they interact with your website.

If you build a product options app​

The same advice applies, and there is nothing you need to add on your side. 3D Bits reads whatever your app renders, so an app built from real form fields with reasonably stable name attributes works with us out of the box, and your merchants can pair it with a 3D configurator without either of us doing integration work.

Two things help those merchants in practice. Keep field names stable across releases, since a rename silently breaks any configuration built against the old name. And if your app renders its controls after the page loads, make sure changes fire an ordinary change or input event, which is what a swap gets picked up from.

If you would like to check how your app behaves alongside 3D Bits, install both on a development store and turn on Debug Mode. It lists every field name and value we can see on the page, which is usually enough to answer the question in a couple of minutes. We are happy to look at the results with you, at [email protected].