How KHR_materials_variants Enables glTF Colorways

The KHR_materials_variants extension allows a single glTF or GLB 3D asset to store multiple material variations—such as different colors, patterns, and finishes—without duplicating the underlying geometry. By defining a global list of variant names and mapping them to specific materials directly within the mesh primitives, 3D commerce platforms and configurators can instantly switch visual styles in real time. This approach dramatically reduces file size, cuts network requests, and streamlines 3D asset management for multi-SKU products.

The Architecture of KHR_materials_variants

In standard glTF 2.0, each mesh primitive can only reference a single material. Traditionally, displaying five different color options of a chair required exporting five separate 3D models or writing complex, custom JavaScript logic to swap textures manually at runtime.

KHR_materials_variants solves this by introducing a standardized architecture based on two core components:

  1. The Root Variants Array: At the document root level, the extension defines an array of named variants (for example: "Red Leather", "Blue Velvet", or "Matte Black").
  2. Primitive-Level Material Mappings: Within each mesh primitive, the extension attaches a mapping table. This table pairs a specific material index with one or more variant indices defined in the root array.

When a 3D runtime loads the file, it defaults to the primary material assigned to the primitive. When a user selects a variant from a UI, the viewer reads the mapping table and swaps the active material to the one associated with the selected variant index.

Eliminating Geometry Duplication

The most significant technical advantage of this extension is geometry reuse. A complex 3D product might have tens of thousands of polygons, bone rigs, and morph targets. In a colorway scenario, these structural elements do not change; only the surface properties (albedo, roughness, metallic, normal maps) change.

By packing multiple material references into a single asset:

  • Geometry is downloaded once: Vertices, normals, tangents, and UV coordinates are shared across all variants.
  • Draw calls and memory footprints are optimized: The GPU retains the mesh buffer in memory, changing only shader parameters or texture bindings when switching colorways.
  • File sizes are minimized: A product with ten colorways is only marginally larger than a single-variant model, as the only added data consists of small JSON mapping blocks and additional texture maps.

Dynamic Asset Management for E-Commerce

KHR_materials_variants has become the standard for digital retail and product configurators. Because variant metadata is baked natively into the asset specification, it works predictably across different WebGL, WebGPU, and native engines (such as Babylon.js, Three.js, and Google’s <model-viewer>).

Digital asset pipelines no longer need to maintain separate files for every product SKU. Instead, artists export a single master asset that accurately represents the entire product catalog, enabling instant, lag-free visual switching on product display pages.