# hangr shopify integration

v2.4.1 Updated April 13, 2026

Hangr integrates with Shopify via a native **Theme Block**. Once installed, a "View in 3D" button appears on your product pages. Shoppers click it to open a full-screen 3D viewer — no app store required, no redirects.

The block reads a 3D viewer URL from a product metafield, so each product in your catalog links to its own model. Installation takes about 10 minutes and requires no coding knowledge.

{% hint style="warning" %}
**Work on a duplicate theme first**

Before making any changes to your live theme, go to **Online Store → Themes**, click the ··· menu on your current theme, and select **Duplicate**. Do all of the steps below on the duplicate. Only publish it when everything looks correct.
{% endhint %}

## Before you start

Check that the following are in place before installing the block.

* **Your theme supports Shopify 2.0 blocks**\
  The Hangr block requires a Shopify 2.0 theme (Online Store 2.0). All themes released after 2021 support this. See the [Theme Compatibility](#compatibility) section if you're unsure.
* **You have at least one 3D model generated in Hangr**\
  Log into your Hangr dashboard and generate a model for a product. Copy the hosted viewer URL from the model detail page — you'll need it for the metafield step.
* **You have access to your Shopify Theme Editor**\
  You'll need to edit theme code. Go to **Online Store → Themes → ··· → Edit code** on your *duplicate* theme.

## Installing the block

The block is a single `.liquid` file that you paste into your theme's blocks folder. No dependencies, no npm, no build step.

{% stepper %}
{% step %}

#### Open your duplicate theme's code editor

In Shopify admin, go to **Online Store → Themes**. On your *duplicate* theme, click **··· → Edit code**.
{% endstep %}

{% step %}

#### Create a new block file

In the left sidebar, find the **Blocks** folder. Click **Add a new block**. Name it exactly: `hangr-view-in-3d`. Click **Done**.
{% endstep %}

{% step %}

#### Paste the block code

Delete all placeholder content in the new file. Paste the full block code from the [Block Code](#block-code) section below. Click **Save**.
{% endstep %}

{% step %}

#### Add the block to your product template

Go to **Online Store → Themes → Customize** (on your duplicate theme). Navigate to a product page. In the left sidebar, find the **Product information** section. Click **Add block** and select **View in 3D by Hangr**. Drag it to position it below your Add to Cart button. Click **Save**.
{% endstep %}

{% step %}

#### Verify the block appears

The "View in 3D" button should now be visible in the Theme Editor preview. If no button appears, the product does not yet have a viewer URL metafield set — complete the metafield step below and return to check.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
**The button only appears when a metafield URL is set**

The block is designed to be invisible by default. It only renders on a product page if that product has a `custom.3d_viewer_url` metafield with a valid URL. Products without a metafield will show nothing — so it's safe to install across your entire theme.
{% endhint %}

## Setting up metafields

Metafields are how Shopify stores custom data per product. You need to create metafield definitions once, then populate a URL value for each product you want to show the 3D viewer on.

### Step 1 — Create the metafield definition

Go to **Shopify Admin → Settings → Custom data → Products**. Click **Add definition** and create the following field:

**Required — Primary viewer URL**

| Namespace & key        | Type             | Required? | Description                                                                                          |
| ---------------------- | ---------------- | --------- | ---------------------------------------------------------------------------------------------------- |
| `custom.3d_viewer_url` | Single-line text | required  | The default Hangr viewer URL for this product. The "View in 3D" button will not appear without this. |

✓

**That's the only required metafield**

For most products, you only need `custom.3d_viewer_url`. The additional view and label metafields below are optional — only create them if you need multi-view support.

### Step 2 — Add the viewer URL to a product

Open any product in **Shopify Admin → Products**. Scroll down to the **Metafields** section at the bottom of the page. Find **3d\_viewer\_url** and paste in the viewer URL from your Hangr dashboard. Click **Save**.

Your viewer URL from Hangr will look like: `https://hangr.tech/v/[your-model-id]`

Once saved, visit the product page on your storefront — the "View in 3D" button should now appear.

## Multi-view setup (optional)

If a product has multiple variants with different 3D models — for example, a luggage product with a cabin size and a checked size — you can show toggle chips inside the viewer so shoppers can switch between them. This requires setting up additional optional metafields.

**Optional — Additional views & labels**

| Namespace & key                  | Type             | Required? | Description                                                                         |
| -------------------------------- | ---------------- | --------- | ----------------------------------------------------------------------------------- |
| `custom.3d_viewer_url_view1`     | Single-line text | optional  | Viewer URL for a second 3D model. Enables the View 1 toggle chip inside the viewer. |
| `custom.3d_viewer_url_view2`     | Single-line text | optional  | Viewer URL for a third 3D model. Enables the View 2 toggle chip inside the viewer.  |
| `custom.3d_viewer_label_default` | Single-line text | optional  | Display label for the default view chip. Overrides the block setting. E.g. "Cabin"  |
| `custom.3d_viewer_label_view1`   | Single-line text | optional  | Display label for the View 1 chip. E.g. "Checked"                                   |
| `custom.3d_viewer_label_view2`   | Single-line text | optional  | Display label for the View 2 chip. E.g. "Large"                                     |

### How the toggle chips behave

| Metafields set            | What the viewer shows                                 |
| ------------------------- | ----------------------------------------------------- |
| Default URL only          | Single viewer, no chips                               |
| Default + View 1          | Two chips — toggle between Default and View 1         |
| Default + View 1 + View 2 | Two chips always visible showing the non-active views |

{% hint style="info" %}
**Labels fall back to block settings**

If a label metafield is left blank, the block uses the label configured in the Theme Editor block settings as a fallback. You can set default labels once in the block settings and only override per-product when needed.
{% endhint %}

## Button styling

The "View in 3D" button inherits your theme's native button styles by default — no extra setup needed. You can also customise it from within the Theme Editor.

### Using a preset style

In the Theme Editor, click the Hangr block in the sidebar. Under **Button Style**, choose from:

* **Primary** — your theme's main filled button style
* **Secondary** — your theme's secondary button style (default)
* **Outline** — your theme's outline/ghost button style

### Custom styling (advanced)

Enable **Enable Custom Styling** in the block settings to unlock full control over background color, text color, border, hover states, font size, weight, padding, border radius, and letter spacing — all configurable without touching code.

{% hint style="warning" %}
**Custom styling overrides all theme styles**

When custom styling is enabled, it takes full precedence. If you switch themes later, you'll need to re-check the button colors. Using the preset styles (Primary / Secondary / Outline) is more resilient across theme changes.
{% endhint %}

## Theme compatibility

The Hangr block requires a **Shopify 2.0 theme** that supports the Theme Blocks system. Themes using the older Sections/Snippets architecture (pre-2021) are not supported.

| Theme            | Support           | Notes                                                                    |
| ---------------- | ----------------- | ------------------------------------------------------------------------ |
| Dawn             | supported         | Shopify's default OS 2.0 theme. Validated on Dawn 14.x and 15.x.         |
| Craft            | supported         | OS 2.0. Block installs cleanly into the Product information section.     |
| Sense            | supported         | OS 2.0. Standard block installation.                                     |
| Studio           | supported         | OS 2.0. Standard block installation.                                     |
| Refresh          | supported         | OS 2.0. Standard block installation.                                     |
| Crave            | supported         | OS 2.0. Standard block installation.                                     |
| Ride             | supported         | OS 2.0. Standard block installation.                                     |
| Origin           | supported         | OS 2.0. Standard block installation.                                     |
| Impulse (2022+)  | likely compatible | Updated to OS 2.0. Not officially validated — test on a duplicate first. |
| Prestige (2022+) | likely compatible | Updated to OS 2.0. Not officially validated — test on a duplicate first. |
| Turbo            | likely compatible | Updated to OS 2.0 in recent versions. Check your version number.         |
| Debut            | not supported     | Legacy theme (pre-OS 2.0). Uses snippets, not blocks.                    |
| Brooklyn         | not supported     | Legacy theme. Uses snippets architecture.                                |
| Boundless        | not supported     | Legacy theme. Uses snippets architecture.                                |
| Narrative        | not supported     | Legacy theme. Uses snippets architecture.                                |
| Simple           | not supported     | Legacy theme. Uses snippets architecture.                                |
| Venture          | not supported     | Legacy theme. Uses snippets architecture.                                |
| Supply           | not supported     | Legacy theme. Uses snippets architecture.                                |

{% hint style="warning" %}
**Not sure if your theme is OS 2.0?**

In the Theme Editor, if you can see a **Blocks** section inside your product template's sidebar and can add blocks directly — you're on OS 2.0. If you only see Sections with no nested blocks, your theme is likely legacy and not supported.
{% endhint %}

## FAQ

<details>

<summary>The button isn't appearing on the product page</summary>

The most common reason is that the product doesn't have a `custom.3d_viewer_url` metafield set. The block is intentionally invisible when no URL is present. Check the product's metafields in Shopify Admin and make sure the URL is saved correctly.

</details>

<details>

<summary>The block doesn't appear in the "Add block" list</summary>

Make sure the `hangr-view-in-3d.liquid` file was saved inside the **Blocks** folder (not Snippets or Sections). If you saved it in the wrong folder, delete it and re-create it in the correct location.

</details>

<details>

<summary>Can I add the block to collection pages or the homepage?</summary>

The block is designed for product pages only — it reads data from the `product` Liquid object, which is only available on product templates.

</details>

<details>

<summary>Will it work if I change themes later?</summary>

You'll need to re-install the block file in the new theme and re-add it via the Theme Editor. The metafields on your products stay in place — so once the block is re-installed, all your products will work immediately.

</details>

<details>

<summary>Do I need to install anything from the Shopify App Store?</summary>

No. The Hangr block is a standalone theme file — there is no Shopify app to install. Your subscription and model management happen entirely through the Hangr dashboard at `hangr.tech`.

</details>

<details>

<summary>My theme has a custom product template. Do I need to do anything different?</summary>

No. As long as your theme is OS 2.0, you can add the Hangr block to any product template variant through the Theme Editor. Navigate to the correct template in the Theme Editor's template selector and add the block there.

</details>

## Full block code

Copy the entire code below and paste it into your new `hangr-view-in-3d.liquid` block file. Do not modify the code unless you are comfortable with Liquid and JavaScript.

hangr-view-in-3d.liquid

```liquid
{% comment %} ============================================================ View in 3D Button Block by Hangr Solutions Version 2.4.1 — https://hangr.tech ============================================================ METAFIELDS USED: Required: custom.3d_viewer_url — Primary viewer URL Optional: custom.3d_viewer_url_view1 — Second view URL custom.3d_viewer_url_view2 — Third view URL custom.3d_viewer_label_default — Label for default view chip custom.3d_viewer_label_view1 — Label for view 1 chip custom.3d_viewer_label_view2 — Label for view 2 chip The button only renders when custom.3d_viewer_url is set. ============================================================ {% endcomment %} {% liquid # Resolve primary URL (supports legacy key fallbacks) assign product_3d_url = product.metafields.custom['3d_viewer_url'] if product_3d_url == blank assign product_3d_url = product.metafields.custom.viewer_3d_url endif if product_3d_url == blank assign product_3d_url = product.metafields.custom.threed_viewer_url endif # Resolve alternate view URLs assign product_3d_url_view1 = product.metafields.custom['3d_viewer_url_view1'] assign product_3d_url_view2 = product.metafields.custom['3d_viewer_url_view2'] # Resolve view labels (metafield overrides block setting) assign label_default = product.metafields.custom['3d_viewer_label_default'] if label_default == blank assign label_default = block.settings.toggle_label_default endif assign label_view1 = product.metafields.custom['3d_viewer_label_view1'] if label_view1 == blank assign label_view1 = block.settings.toggle_label_view1 endif assign label_view2 = product.metafields.custom['3d_viewer_label_view2'] if label_view2 == blank assign label_view2 = block.settings.toggle_label_view2 endif # Unique ID for this block instance assign unique_id = 'view3d-' | append: block.id # Button class from style preset assign button_class = 'view3d-button' if block.settings.button_style == 'primary' assign button_class = button_class | append: ' button' elsif block.settings.button_style == 'secondary' assign button_class = button_class | append: ' button-secondary' elsif block.settings.button_style == 'outline' assign button_class = button_class | append: ' button-outline' endif assign use_overrides = block.settings.enable_style_overrides assign has_view1 = false assign has_view2 = false if product_3d_url_view1 != blank assign has_view1 = true endif if product_3d_url_view2 != blank assign has_view2 = true endif %} {# Only render if a primary URL is set #} {% if product_3d_url != blank %} <!-- Full block HTML, CSS, and JS are included in the downloaded .liquid file --> <!-- Paste the complete contents of hangr-view-in-3d.liquid here --> {% endif %} {% schema %} { "name": "View in 3D by Hangr", "target": "section", "settings": [ { "type": "text", "id": "button_text", "label": "Button Text", "default": "View in 3D" }, { "type": "checkbox", "id": "show_icon", "label": "Show 360° icon", "default": true }, { "type": "text", "id": "toggle_label_default", "label": "Default View Label", "default": "Default View" }, { "type": "text", "id": "toggle_label_view1", "label": "View 1 Label", "default": "View 1" }, { "type": "text", "id": "toggle_label_view2", "label": "View 2 Label", "default": "View 2" }, { "type": "select", "id": "button_style", "label": "Style Preset", "options": [ { "value": "primary", "label": "Primary" }, { "value": "secondary", "label": "Secondary" }, { "value": "outline", "label": "Outline" } ], "default": "secondary" }, { "type": "checkbox", "id": "enable_style_overrides", "label": "Enable Custom Styling", "default": false } ], "presets": [{ "name": "View in 3D by Hangr", "category": "Product" }] } {% endschema %}
```

{% hint style="warning" %}
**Download the full file from your Hangr dashboard**

The code above shows the block structure for reference. The full, deployable `hangr-view-in-3d.liquid` file — including all CSS and JavaScript — is available to download from **Hangr Dashboard → Integrations → Shopify**. Always use the downloaded file to ensure you have the latest version.
{% endhint %}

## Metafield reference

Complete reference for all metafields used by the Hangr block.

All metafields — Namespace: `custom`

| Key                       | Type             | Status   | Purpose                                                                   |
| ------------------------- | ---------------- | -------- | ------------------------------------------------------------------------- |
| `3d_viewer_url`           | Single-line text | required | Primary viewer URL. The button does not render without this.              |
| `3d_viewer_url_view1`     | Single-line text | optional | URL for a second 3D model. Enables the View 1 toggle chip.                |
| `3d_viewer_url_view2`     | Single-line text | optional | URL for a third 3D model. Enables the View 2 toggle chip.                 |
| `3d_viewer_label_default` | Single-line text | optional | Per-product label for the default view chip. Falls back to block setting. |
| `3d_viewer_label_view1`   | Single-line text | optional | Per-product label for the View 1 chip. Falls back to block setting.       |
| `3d_viewer_label_view2`   | Single-line text | optional | Per-product label for the View 2 chip. Falls back to block setting.       |

{% hint style="info" %}
**Legacy key fallbacks**

The block also checks `custom.viewer_3d_url` and `custom.threed_viewer_url` as fallbacks for the primary URL field. These are for backwards compatibility only. New installs should use `custom.3d_viewer_url`.
{% endhint %}

Hangr Solutions · [hangr.tech](https://hangr.tech/)

Block v2.4.1 · April 2026


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hangr.gitbook.io/hangr-docs/hangr-shopify-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.