User Guide

Setting up Noorifa on a WooCommerce product

Everything you need to add a spinnable, zoomable 3D view to a product page — no code required. WooCommerce still handles pricing, stock, variations and checkout exactly as it always has.

What Noorifa does

Noorifa adds an interactive 3D viewer to a WooCommerce product page. Instead of (or alongside) static product photos, customers can rotate, zoom, and switch between colors or materials on a real 3D model of the product — while WooCommerce keeps handling everything it already does: price, stock, variations, cart and checkout.

You upload a .glb/.gltf 3D model to a product, once, in the product editor.
↓
Define Appearances
Named looks like "Red" or "Oak Wood" — a color or texture per part of the model.
Map to WooCommerce
Connect a product attribute (e.g. Color) so picking a value swaps the 3D appearance.
Tune Camera & Viewer
Background, lighting, zoom/pan, auto-rotate — all optional.
↓
Customers see it on the product page — swatches drive the same variation selector WooCommerce already shows, so price and stock still update normally.
ⓘ

Nothing is replaced. If a customer's browser doesn't support 3D (WebGL), JavaScript is off, or the model fails to load for any reason, they simply see your normal WooCommerce product gallery — the 3D viewer only ever adds to the page, never removes your existing photos.

Requirements

  • WooCommerce must be installed and active. Noorifa has nothing to attach a 3D viewer to without it.
  • PHP 8.1 or higher on your hosting.
  • A .glb or .gltf 3D model of your product — typically exported from Blender, SketchUp, or a similar 3D tool. If you don't have one yet, a freelance 3D artist or your product manufacturer's CAD team can usually produce one.
⚠

If WooCommerce isn't active, Noorifa shows an admin notice explaining what's missing and stays switched off — it won't error or break your site.

Installing & activating

  1. Upload the plugin — via Plugins → Add New → Upload Plugin, or by copying the noorifa folder into wp-content/plugins/.
  2. Activate it from the Plugins screen.
  3. Confirm WooCommerce is active — if it isn't, Noorifa will tell you on the Plugins screen and won't do anything until it is.
  4. Open any product in Products → All Products → Edit, and scroll down to the "Noorifa – 3D Product Viewer" box beneath the main content editor.

Setting Up a Product

Enable the 3D viewer

Every setting in Noorifa lives on a per-product basis, inside a tabbed box on the product editor screen. The tabs run down the left side, mirroring WooCommerce's own Product Data panel:

General
3D Model
Appearance
WooCommerce Mapping
Camera & Lighting
Viewer
Export / Import
The active tab's settings appear here. Nothing is saved until you click WooCommerce's own Update/Publish button for the product.

On the General tab, tick Enable Noorifa to turn the 3D viewer on for this product. Leave it unticked and the product behaves exactly as it did before Noorifa was installed.

ⓘ

Even with this ticked, the 3D viewer stays invisible on the frontend until this product also has a model uploaded and at least one appearance defined — see the next two sections. There's no way to accidentally show a half-configured viewer to a customer.

Upload a 3D model

Open the 3D Model tab and click Select 3D Model. This opens WordPress's normal Media Library picker — upload a new .glb or .gltf file, or pick one you've already uploaded.

  1. Choose the file. Once selected, a live preview of the model loads directly in the admin screen so you can confirm it's the right one and see it rendered in 3D immediately.
  2. Meshes are detected automatically. Every named part of the model (e.g. "Tabletop", "Leg_Front_Left") appears in the Detected meshes list below the preview — you'll use these names in the next step, Appearances.
  3. Save the product (Update/Publish) so the mesh list is available to the Appearance tab.
⚠

If the file was accepted by your Media Library but doesn't preview, double-check it's a valid glTF binary (.glb) or glTF JSON (.gltf) export, and see Troubleshooting below for the most common causes.

Detected meshes & Draco compression

Noorifa reads mesh names directly out of the 3D file — there's nothing to type in by hand. Good, descriptive mesh names in your 3D authoring tool (Blender, etc.) make the next step, Appearances, much easier to work through, since you'll be matching each mesh name to a color or texture.

ⓘ

If Noorifa warns that your model "isn't using Draco compression," that's the single biggest thing you can do to speed up loading for your customers, especially on larger or more detailed models. In Blender, re-export using the glTF exporter with its Compression option turned on — the model looks identical, just loads faster.

Appearances

Creating appearances

An Appearance is a named "look" for the product — e.g. "Red", "Oak Wood", "Matte Black" — that describes what every mesh in the model should look like when that look is selected. On the Appearance tab, click Add Appearance and give it a name.

For each detected mesh, choose one of three options:

Default

Leaves that part exactly as it was exported from your 3D tool — its own original material and color. Useful for parts that never change between appearances, like metal hardware or glass.

Color

Pick a flat color with the built-in color picker. Good for painted or dyed surfaces.

Texture

Pick an image from the Media Library to wrap onto that part (e.g. a wood grain or fabric photo), with a Tile × setting to control how large or small the pattern repeats across the surface.

You don't have to set every mesh for every appearance — leave anything unchanged at Default. Add as many appearances as you need (one per color/material option you sell).

Color, texture, or default — which to use

  • Use Color for solid paint/finish options (e.g. "Red", "Matte Black").
  • Use Texture for anything with a visible pattern or grain (e.g. "Oak Wood", "Herringbone Fabric") — start with a tile value of 1 and increase it if the pattern looks too stretched/large on the model.
  • Leave a mesh at Default for parts that should look the same in every appearance, like screws, glass, or a logo plate.

Connecting to WooCommerce

Attribute mapping

Appearances only become selectable by customers once you connect them to a WooCommerce product attribute (like "Color" or "Material") on the WooCommerce Mapping tab. This is what turns your appearances into swatches on the live product page, and keeps them wired to WooCommerce's own price/stock variation logic.

⚠

This tab needs a product attribute that's marked "Used for variations" in the Attributes tab first, with variations already created on the Variations tab. If you haven't set those up yet in WooCommerce, do that first — this tab will tell you if there's nothing to map yet.

  1. Click "Add Attribute Mapping" and choose which variation attribute should drive appearance switching (e.g. "Color").
  2. For each value of that attribute (e.g. "Silver", "Gold"), pick which Appearance it should show.
  3. Repeat for a second attribute if needed — e.g. "Table Color" and, independently, "Leg Color" can each control different meshes at the same time, without interfering with each other.

On the frontend, Noorifa automatically builds a swatch for each value from whichever mesh actually visibly differs between your mapped appearances — there's no separate "swatch preview" setting to maintain by hand.

The "Any" value warning

If you see a warning that every variation has "Any" selected for a mapped attribute, it means WooCommerce itself has no way to tell those variations apart by that attribute. The 3D appearance will still visually swap when a customer clicks a swatch, but the price and stock will not update, because as far as WooCommerce is concerned every variation matches equally.

⚠

This is a WooCommerce product-data setting, not something Noorifa can work around from the swatch itself. Fix it on the product's Variations tab: give each variation a specific value for that attribute instead of "Any".

Camera & Lighting

Background

On the Camera & Lighting tab, choose between:

Solid Color

Pick any flat color with the built-in color picker.

Gradient

Choose from 8 studio-photography-style presets: Studio White, Soft Grey, Warm Sand, Cool Slate, Sage Green, Blush Pink, Charcoal, and Midnight Blue.

The background sits behind the 3D model on the product page, similar to a seamless paper backdrop in a photo studio.

Distance, brightness & motion

Camera Distance

How close the camera starts relative to the product. Lower is a closer starting view, higher is farther back. 1.0 is the default, auto-computed framing.

Lighting Brightness

Turns the overall light intensity up or down.

Auto-Rotate

Slowly and continuously spins the model, with its own adjustable speed.

Cinematic Reveal

A one-time smooth camera glide into the default view the moment the model finishes loading. Combines with Auto-Rotate — they aren't mutually exclusive.

Viewer Behavior

Aspect ratio, zoom & pan

On the Viewer tab:

  • Aspect Ratio — Square (1:1), Landscape (4:3), or Portrait (3:4). Choose whichever best matches the shape of your product and the space your theme gives the gallery.
  • Allow zoom — lets customers scroll/pinch to zoom in for a closer look.
  • Allow pan — lets customers right-click-drag (desktop) or two-finger-drag (mobile) to shift the view sideways.

Both controls are on by default. Turning either off simplifies the viewer to rotate-only, which can feel more focused for very simple products.

Export & Import

Moving a configuration between products or sites

The Export / Import tab lets you copy one product's entire Noorifa setup — enabled state, model reference, appearances, attribute mappings, and camera/viewer settings — to another product, or another WordPress site running Noorifa.

  1. Export — click Export Settings to download a .json file describing this product's configuration.
  2. Import — on the target product, choose that .json file and click Import Settings.
⚠

The 3D model and any texture images referenced in the file must already exist in the target site's Media Library — Noorifa matches them by re-checking the file, not by copying the media itself. If something's missing, the import still completes, and you'll see exactly which model or texture to re-upload.

Help

Troubleshooting

The model won't load / "Could not load the 3D model file"

  • Mixed content (HTTPS sites): if your site loads over https:// but the browser console shows a Blocked loading mixed active content "http://…" error for the model URL, your WordPress Site Address (URL) and WordPress Address (URL) under Settings → General need to both be set to https://. This is the single most common cause of a model that "used to work" suddenly failing after enabling SSL.
  • Confirm the file is actually a valid .glb or .gltf export, not renamed from another format.
  • Open your browser's console (F12) on the product page — every message Noorifa logs is prefixed [Noorifa], including the specific reason a load failed.

The viewer shows up in the wrong place, or not positioned correctly

Noorifa places itself inside your theme's own .woocommerce-product-gallery element, so it inherits your theme's existing gallery layout automatically. Page builders that render fully custom product-image markup (e.g. Elementor Pro's Theme Builder) may not provide that element — in that case the viewer still displays, just without theme-matched positioning. The browser console will note this with a [Noorifa] warning.

Swatches change the look but not the price or stock

See The "Any" value warning above — this means the mapped attribute's variations all have "Any" selected in WooCommerce and need specific values set per variation.

Nothing shows up at all

  • Check Enable Noorifa is ticked on the General tab.
  • Check a 3D model is uploaded on the 3D Model tab.
  • Check at least one Appearance is defined on the Appearance tab.
  • The customer's browser must support WebGL — extremely old browsers or locked-down corporate/kiosk browsers may not. Noorifa falls back to your normal gallery automatically in this case, without an error to the customer.

Does Noorifa send my product data anywhere?

No. Noorifa doesn't connect to any external service, API, or CDN at runtime. Three.js (the 3D rendering engine) and the Draco decoder are bundled with the plugin itself, so nothing is fetched from a third party. All uploaded models and images stay in, and are served from, your own Media Library.

FAQ

Does Noorifa work with any WooCommerce theme?

Yes, on a best-effort basis. Noorifa hooks into standard WooCommerce actions and slots into whatever gallery layout your active theme already applies — including block/FSE themes that render the gallery as its own Gutenberg block.

Will Noorifa conflict with other plugins?

Every hook, option and meta key Noorifa uses is prefixed noorifa/_noorifa_, and it doesn't bundle a Composer autoloader — the most common causes of plugin-to-plugin conflicts.

What happens to my settings if I uninstall Noorifa?

Uninstalling (not just deactivating) the plugin through the Plugins screen removes all of its per-product settings. Deactivating alone leaves everything in place, ready to pick back up if you reactivate.