On this page
KHR_materials_variants
KHR_materials_variants
A Khronos-ratified glTF 2.0 extension that packs multiple material/colour variants for identical geometry into a single glTF/GLB file, enabling instant runtime switching between product colourways without re-downloading geometry. In an ecommerce context it collapses N separate glTF files (one per SKU colour) into a single asset, eliminating per-variant network round-trips and enabling client-side variant switching inside product viewers.
Spec status
- Status: Complete, ratified by the Khronos Group (as-of 2026-09-25, [KhronosGroup/glTF GitHub](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_materials_variants))
- Written against: glTF 2.0
- Ratification date: November 2020 — confirmed by Khronos 3D Commerce Working Group Q&A blog (December 8, 2020), in which Jon Wade (Shopify Product Manager) stated "This extension was just ratified."
- Origin: First proposed by Stephan Leroux (Shopify) as a Facebook vendor extension in October 2019 (Three.js issue #17808, glTF proposal #1681), then promoted to KHR status via the Khronos 3D Commerce Working Group.
- Copyright: 2018–2020 The Khronos Group Inc.
- Version: No explicit semver on the extension; it lives in-place in
extensions/2.0/Khronos/KHR_materials_variants/of the main glTF repository.
How it works
Two core data structures (from spec README):
variantsarray at the glTF root — a list of named variant objects, each with anamestring (e.g."Yellow Sneaker","Red Sneaker"). Each name typically maps to a distinct SKU or product option.mappingsarray on each mesh primitive — maps variant indices to specific material indices. Each entry specifies whichmaterial(by root material array index) applies when a given set ofvariants(by root variant array index) is active.
Runtime behaviour: The viewer tracks one "active variant" at a time. On a variant switch, it traverses all primitives and applies the material mapped to the selected variant index. If no mapping matches the active variant, the viewer falls back to the primitive's default material. Primitives not involved in any variant are unaffected.
Design constraints (spec non-goals, from Khronos blog November 2020 and glTF Transform docs):
- Variants are finite and pre-authored — not dynamically generated at runtime.
- Geometry cannot change per variant — only materials. A companion extension
[[KHR_mesh_variants]]was noted as "under consideration" for geometry-level switching; not ratified as of 2026-09-25. - Multi-dimensional variants (e.g. colour + fabric) must be flattened into a single named list.
- The extension handles display/delivery, not configuration business logic.
Lazy loading: With external texture URIs (.gltf + separate texture files rather than
a self-contained .glb), viewers can lazily fetch textures for inactive variants only when
the user selects them.
Download size impact
From the Khronos announcement blog (as-of 2020-11-11, Khronos blog):
- Example: 3 shoe colour variants at ~5 MB each (4 MB geometry + 1 MB textures).
- Without extension: 3 × 5 MB = 15 MB (N separate glTF files).
- With extension: 4 MB geometry + ~1 MB per variant activated ≈ 6–7 MB at full utilisation.
- Approximate reduction: ~53% for a 3-variant product.
These figures are from the 2020 ratification blog post. Actual production savings vary by texture resolution, compression (KTX2/Basis Universal), and CDN behaviour. No 2024–2026 primary study was surfaced.
Engine and viewer support
| Engine / Viewer | Status | Notes |
|---|---|---|
| Babylon.js | ✅ First-class, confirmed | BABYLON.GLTF2.Loader.Extensions.KHR_materials_variants TypeDoc class; listed in GLTFLoaderExtensionOptions; confirmed through v9.x (as-of 2026-09-25); support added post-ratification Nov 2020 (exact version unconfirmed) |
| Google model-viewer | ✅ Confirmed | availableVariants property + variantName attribute; null reverts to initial material; elalish (Google) confirmed implementation Dec 2020 in Three.js PR discussion; GLTFExporterMaterialsVariantsExtension in source |
| Three.js (GLTFLoader) | ⚠️ Plugin only (by design) | PR #20789 deliberately closed Feb 2021; Three.js maintainers decided not to add glTF-specific APIs to core objects; raw extension data in .userData.gltfExtensions['KHR_materials_variants']; official example webgl_loader_gltf_variants.html exists; third-party plugin at takahirox/three-gltf-plugins |
| glTF Transform | ✅ Full read/write | KHRMaterialsVariants class in @gltf-transform/extensions; createVariant, createMapping, createMappingList methods |
| Blender | ✅ Native export (3.x+) | Multiple community tutorials (2022) confirm native KHR_materials_variants export in Blender's glTF exporter |
| Threepipe | ✅ Plugin | GLTFKHRMaterialVariantsPlugin with API and UI |
| Filament / Android | ❓ Unconfirmed | No explicit evidence of support surfaced (gap) |
| Adobe Substance | ❓ Unconfirmed | Community feature request found (~2023); no confirmation of implementation |
Three.js "supported" framing: Three.js is often listed as "supporting" KHR_materials_variants (e.g. in glTF compatibility tables) without noting that the extension handler is not bundled in core GLTFLoader — it requires a separate plugin or the example code. The Khronos forums and PR #20789 confirm this is an intentional design choice (Don McCurdy and Three.js maintainers), not an omission. Source 1 (listing "Three.js: supported"): various glTF compatibility reference pages. Source 2 (design decision): Three.js PR #20789, Feb 2021, and Khronos glTF forums.
Ecommerce and retail context
Who built it: The Khronos 3D Commerce Working Group, formed ~2019 when Wayfair and IKEA approached Khronos to reduce friction in 3D content pipelines. Chair: Shrenik Sadalgi (Director of R&D, Wayfair). Key spec contributors: Shopify (Daniel Beauchamp, Stephan Leroux, Jon Wade), Facebook/Meta (Pär Winzell, Renee Rashid, Jeremy Cytryn), Adobe (Mike Bond), Wayfair (Eric Chadwick), Emersya (Aurélien Vaysset). Source: Khronos 3D Commerce Working Group Q&A blog, December 8, 2020.
Retail deployment pattern: One GLB per product containing all colourways. A viewer exposes a variant dropdown. Each variant name maps to a distinct SKU. Client-side switching requires no network round-trip after initial load.
Shopify: Representatives (Beauchamp, Leroux, Wade) publicly described KHR_materials_variants as the mechanism for merging SKU colour variants into a single asset in Shopify's 3D commerce pipeline. Shopify natively supports GLB for 3D product pages. Source: Khronos 3D Commerce Q&A blog, December 2020.
Google Merchant Center: Supports glTF/GLB model links for 3D product experiences in Shopping results for home goods and shoes (as-of 2024–2025). Source: Google Merchant Center documentation (surfaced via web agent, 2026-09-25).
Wayfair AR return rate and IKEA purchase confidence statistics cited in the wider 3D commerce literature (e.g. "Wayfair AR users return 35% less", "IKEA AR users 98% purchase confidence") date to ~2020–2021 and cannot be traced to primary publications. Treat as indicative rather than current benchmarks.
Relationship to KHR_interactivity and the glTF extension ecosystem
KHR_interactivity was submitted for Khronos ratification July 16, 2026. It embeds portable behavior graphs (DAG of event/action/logic nodes) directly in glTF assets, enabling user-interaction-triggered state changes without external JavaScript.
The two extensions are complementary:
KHR_materials_variants= data model — defines which materials exist per primitive per variant, and their names.KHR_interactivity= trigger logic — behavior graphs can callKHR_materials_variantsvariant switches in response to clicks, hovers, or scene events.
Together they enable fully self-contained 3D product configurators with no external JavaScript.
Companion interaction extensions: [[KHR_node_selectability]], [[KHR_node_hoverability]],
[[KHR_node_visibility]].
Planned: [[KHR_mesh_variants]] — geometry-level switching (different shapes per variant,
not just materials). Not ratified as of 2026-09-25.
Source: glTF Transform docs; KHR_interactivity press release, Khronos, July 16, 2026.
Khronos 3D Commerce Working Group outputs
The Working Group that produced this extension also maintains:
- 3D Commerce Viewer Certification Program — formal certification for visual consistency
across viewers; KHR_materials_variants support is required for compliant viewers. Certified
viewers listed at
khronos.org/3dcommerce/certification/certified-viewers/. - Asset Creation Guidelines 2.0 (August 2025) — living document covering PBR Next extensions, mesh compression, animation, UV guidance; the production framework within which variant-enabled assets are authored. Source: Khronos blog, "Introducing Asset Creation Guidelines 2.0", August 2025.
- PBR Neutral Tone Mapper — adopted by model-viewer, Babylon.js, Three.js for consistent colour rendering across viewers.
Reference model
MaterialsVariantsShoe (Shopify Inc., CC-BY-4.0) — the canonical demonstration asset,
included in the official KhronosGroup/glTF-Sample-Models repository. Used in the Khronos
launch blog, model-viewer scenegraph examples, and Three.js variant example.
Market size context
These are paid-research-sourced market sizing figures; primary Khronos/retailer data on production deployment scale was not available.
- 3D ecommerce global market: $8.53B in 2025 → $10.54B in 2026, 23.6% CAGR (as-of 2026, Research and Markets — purchase required, full report unread).
Key terms
| Term | Meaning |
|---|---|
variants | Root-level array naming each product colourway/option (e.g. "Red", "Blue") |
mappings | Per-primitive array linking variant indices to material indices |
| Active variant | The variant currently displayed by the viewer |
| Default material | The primitive's material used when no variant mapping matches |
| GLB | Binary glTF container; typically used for self-contained single-file delivery |
| PBR | Physically-based rendering — the material model glTF uses |
| KHR | Khronos-ratified extension prefix (vs EXT for vendor-specific) |
Practitioner resources
- Canonical demo: Three.js example —
https://threejs.org/examples/webgl_loader_gltf_variants.html - Reference sample model:
KhronosGroup/glTF-Sample-Models(MaterialsVariantsShoe) - Spec:
https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_materials_variants - 3D Commerce WG:
https://www.khronos.org/3dcommerce/ - Khronos certification list:
https://www.khronos.org/3dcommerce/certification/certified-viewers/ - Blender → Govie Editor pipeline (YouTube, 2022):
https://www.youtube.com/watch?v=X-2GPYSZUk0 - Khronos SIGGRAPH 2025 "glTF & 3D Commerce" BOF:
https://www.youtube.com/watch?v=lc-9xpYUYwY - BuildCores "Scaling 3D on the Web to 1M+ Users" (3D on the Web 2026):
https://www.youtube.com/watch?v=aTzEx5lz4JA