3D Interactive Packaging Designer

Quick Start

Get the 3D Packaging Designer running on your HubSpot page in under 5 minutes.

Installation

Requirements

• HubSpot CMS Professional or Enterprise (required for custom modules)
• Visitors need a WebGL-capable browser (all modern browsers since 2015)
• No jQuery dependency — the module uses vanilla JavaScript

What Gets Installed

The module installs the following files into your Design Manager:

Custom Modules/
  └── 3d-packaging-designer.module/
      ├── module.html    ← HTML + HubL template
      ├── module.css     ← Scoped styles (all .tpd-* prefixed)
      ├── module.js      ← Three.js scene engine
      ├── fields.json    ← 50 configurable editor fields
      └── meta.json      ← Module metadata & icon

External Dependencies

The module loads Two JavaScript files from the Cloudflare CDN at page render time via HubL require_js():

Configuration Overview

The module has 50 configurable fields organized across two tabs in the HubSpot page editor:

Every field includes inline help text explaining what it does. No code editing is ever required.

Content Tab Reference

Header Group

Brand Logo Group

Enabled Products Group

Toggle each product type on or off. Disabled products don't appear in the visitor-facing selector grid.

Product Colors Group

Each product type has 3 color fields that control the default colors visitors see when the page loads. Visitors can change these in real time using the built-in color pickers.

Features Group

Styles Tab Reference

Style fields follow HubSpot marketplace conventions and are ordered: Text → Background → Border → Spacing → Advanced.

Text Group

Background Group

Border Group

Spacing Group

Advanced Group

Product Types Deep Dive

Each product type is a full 3D model built with Three.js geometry, materials, and lighting. Here's what each includes:

Stand-Up Pouch

A flexible packaging pouch with front face, side gussets, and a resealable zipper. The zipper features visible teeth detail. The label area wraps around the front face.

• Color zones: Body, Zipper, Gusset
• Best for: Coffee, snacks, supplements, pet food, cannabis

Beverage Can

A standard 355ml (12oz) beverage can with pull-tab lid, cylindrical body, and recessed base. Metallic material with realistic reflections.

• Color zones: Body, Lid, Base
• Best for: Energy drinks, craft beer, seltzer, soda

Stick Pack

A tall, narrow single-serve sachet with sealed top and bottom edges. Common in powder supplements and drink mixes.

• Color zones: Body, Seal, Accent stripe
• Best for: Single-serve supplements, drink mixes, condiments

Bar Wrap

A horizontal flow-wrap package with crimped ends, typical of protein bars and chocolate bars.

• Color zones: Outer wrap, Inner foil, Seal
• Best for: Protein bars, chocolate, granola bars

Folding Carton

A rectangular box with lid, front face, and side panels. Rendered with slight bevel edges for realism.

• Color zones: Body, Lid, Accent
• Best for: Cereal, pharmaceuticals, cosmetics, electronics

Bottle

A standard round bottle with screw cap, shoulder taper, and cylindrical body. Label wraps around the center.

• Color zones: Body, Cap, Label background
• Best for: Sauces, supplements, cleaning products

Wine Bottle

A Bordeaux-style wine bottle with foil capsule, long neck, sloped shoulders, and a punt base. Glossy dark glass material.

• Color zones: Glass body, Foil, Label background
• Best for: Wine, spirits, premium olive oil

Slim Drink Can

A tall 250ml slim can (Red Bull format) with narrower diameter and taller profile than the standard beverage can.

• Color zones: Body, Lid, Accent
• Best for: Energy drinks, sparkling water, cocktails

Advanced Usage

Multiple Modules Per Page

The module is multi-instance safe. You can add multiple 3D Packaging Designer modules to the same page without conflicts. Each instance gets a unique DOM ID and scoped Three.js scene. Typical use case: one visualizer for pouches, another for bottles, on the same product page.

Custom Label Artwork

Visitors can upload label images that wrap onto the 3D product surface. Supported formats:

• PNG — Best for labels with transparency
• JPG — Smaller file sizes for photographic labels
• SVG — Vector artwork (rasterized at upload)

Recommended label dimensions: 1024 × 1024px or 2048 × 1024px for best quality on the 3D surface.

PNG Export

The "Download PNG" button captures the current 3D canvas state as a high-resolution PNG image with a transparent background. The exported image matches the visible canvas size. Visitors can use this for internal reviews, presentations, or mockup approvals.

Surface Textures

Material Finishes

Embedding in Blog Posts

The module works in blog posts and blog listing pages. Simply add the module to your blog template's drag-and-drop areas. It's registered for PAGE, BLOG_POST, and BLOG_LISTING template types.

Performance Notes

• Three.js is loaded asynchronously — it won't block page rendering
• The 3D scene initializes only when the module container enters the viewport (intersection observer)
• Shadow maps use 4096×4096 resolution for crisp shadows without excessive GPU load
• On mobile devices, shadow quality is automatically reduced to maintain 60fps
• Total additional page weight: ~160 KB gzipped (Three.js + OrbitControls from CDN, cached after first visit)

Troubleshooting

The 3D preview shows a blank/black area

Products appear but colors don't change

Check that JavaScript is enabled and there are no console errors. Open your browser's Developer Tools (F12) and look for any red error messages. The most common cause is a Content Security Policy (CSP) header blocking inline scripts or the CDN domain. Ensure cdnjs.cloudflare.com is allowed in your CSP.

Module doesn't appear in the page editor

Confirm the module was installed successfully by checking Design Manager → Custom Modules. If it's not listed, try reinstalling from the marketplace. If you see it in Design Manager but not in the page editor's module sidebar, ensure your page template allows custom modules in that zone.

The module looks too small or too large

Adjust the Preview Min Height field in the Styles → Advanced group. Default is 650px. For full-width hero-style layouts, try 800px or higher. The Sidebar Width percentage also affects the preview area size.

Label upload doesn't work

Label upload uses the browser's File API. It won't work if:

• The page is loaded over http:// instead of https:// (HubSpot pages are HTTPS by default)
• The browser blocks file access (incognito mode with strict settings)
• The uploaded file exceeds ~10MB (browser memory constraint)

Module works in preview but not on published page

Click Publish changes in Design Manager after making any edits to the module code. Then republish the page itself. HubSpot caches module assets aggressively — you may need to wait 1-2 minutes or clear your browser cache.

Multiple modules on the same page conflict

This shouldn't happen — the module is multi-instance safe. If you experience issues, check that you haven't manually edited the module code and accidentally removed the instance scoping. Each module instance uses a unique data-module-instance attribute to scope all DOM queries.

Frequently Asked Questions