Skip to main content

ModelViewer

The ModelViewer component renders a 3D model for the Storefront API's Model3d object.

The component outputs a <model-viewer> tag. You can customize this component using passthrough props.

Example code​

import {ModelViewer, gql} from '@shopify/hydrogen';

const QUERY = gql`
  query Products {
    products(first: 5) {
      edges {
        node {
          id
          title
          handle
          media(first: 1) {
            edges {
              node {
                ... on Model3d {
                  mediaContentType
                  id
                  alt
                  previewImage {
                    url
                  }
                  sources {
                    url
                  }
                }
              }
            }
          }
        }
      }
    }
  }
`;

export default function MyProductModel() {
  const {data} = useShopQuery({query: QUERY});

  const firstMediaElement = data.products.edges[0].node.media.edges[0].node;
  if (firstMediaElement.mediaContentType === 'MODEL_3D') {
    return <ModelViewer data={firstMediaElement} />;
  }
}

Props​

NameTypeDescription
children?ReactNodeAny ReactNode elements.
dataPartialDeep&#60;Model3d&#62;An object with fields that correspond to the Storefront API's Model3D object.
loading?"auto" &#124; "lazy" &#124; "eager"A string of either auto, lazy, or eager to indicate the conditions for preloading. Refer to loading in the <model-viewer> documentation.
poster?stringA URL to display an image instead of the model. This is useful for showing the user something before a model is loaded and ready to render. If no URL is provided, then Model3d.previewImage is used. Refer to poster in the <model-viewer> documentation.
reveal?"auto" &#124; "interaction" &#124; "manual"A string of either auto, interaction, or manual to indicate when the model should be revealed. Refer to reveal in the <model-viewer> documentation.
ar?booleanA boolean to enable an AR experience. Refer to ar in the <model-viewer> documentation.
arModes?"webxr" &#124; "scene-viewer" &#124; "quick-look"A prioritized list of webxr, scene-viewer, and/or quick-look to indicate the types of AR experiences to enable. Refer to ar-modes in the <model-viewer> documentation.
arScale?"auto" &#124; "fixed"A string of auto or fixed to control the scaling behaviour. Refer to ar-scale in the <model-viewer> documentation.
arPlacement?"floor" &#124; "wall"A styring of either floor or wall to indicate where to place the object in AR. Refer to ar-placement in the <model-viewer> documentation.
iosSrc?stringThe url to a USDZ model which will be used on supported iOS 12+ devices via AR Quick Look on Safari. Refer to ios-source in the <model-viewer> documentation.
cameraControls?booleanA boolean to enable camera controls. Refer to attributes in the <model-viewer> documentation.
touchAction?"pan-x" &#124; "pan-y" &#124; "none"A string of pan-x, pan-y, or none. Refer to touch-action in the <model-viewer> documentation.
disableZoom?booleanA boolean to disable zoom. Refer to disable-zoom in the <model-viewer> documentation.
orbitSensitivity?numberA number to adjust the speed of theta and phi orbit interactions. Refer to orbit-sensitivity in the <model-viewer> documentation.
autoRotate?booleanA boolean to enable auto rotate. Refer to auto-rotate in the <model-viewer> documentation.
autoRotateDelay?numberA number in milliseconds to specify the delay before auto rotation begins. Refer to auto-rotate-delay in the <model-viewer> documentation.
rotationPerSecond?stringThe speed of auto rotation. Refer to rotation-per-second in the <model-viewer> documentation.
interactionPolicy?"allow-when-focused" &#124; "always-allow"A string of either allow-when-focused or always-allow to indicate whether the viewer requires focus before interacting with it. Refer to interaction-policy in the <model-viewer> documentation.
interactionPrompt?"auto" &#124; "when-focused" &#124; "none"A string of either 'auto', 'when-focused', or 'none' indicating the conditions under which the visual and audible interaction prompt will display. Refer to interaction-prompts in the <model-viewer> documentation.
interactionPromptStyle?"wiggle" &#124; "basic"A string of either wiggle or basic indicating the presentation style of the interaction-prompt when it is raised. Refer to interaction-prompt-style in the <model-viewer> documentation.
interactionPromptThreshold?numberA number to indicate how long the model viewer should wait before prompting the user visually for interaction. Refer to interaction-prompt-threshold in the <model-viewer> documentation.
cameraOrbit?stringA string of the starting orbital position of the camera. Refer to camera-orbit in the <model-viewer> documentation.
cameraTarget?stringA string of the point the camera orbits around. Refer to camera-target in the <model-viewer> documentation.
fieldOfView?stringA string of the vertical field of view of the camera. Refer to field-of-view in the <model-viewer> documentation.
maxCameraOrbit?stringA string of the maxiumum orbital values of the camera. Refer to max-camera-orbit in the <model-viewer> documentation.
minCameraOrbit?stringA string of the minimum orbital values of the camera. Refer to min-camera-orbit in the <model-viewer> documentation.
maxFieldOfView?numberA number indicating the max field of view of the camera. Refer to max-field-of-view in the <model-viewer> documentation.
minFieldOfView?numberA number indicating the min field of view of the camera. Refer to min-field-of-view in the <model-viewer> documentation.
bounds?"tight" &#124; "legacy"A string of tight or legacy for calculating the model's bounding box. Refer to bounds in the <model-viewer> documentation.
interpolationDecay?numberA number indicating the rate of interpolation when the camera or model moves. Refer to interpolation-decay in the <model-viewer> documentation.
skyboxImage?stringA string for the background image of the scene. Refer to skybox-image in the <model-viewer> documentation.
environmentImage?stringA string to control the environmental reflection of the model. Refer to environment-image in the <model-viewer> documentation.
exposure?numberA number indicating the exposure of the model and the skybox. Refer to exposure in the <model-viewer> documentation.
shadowIntensity?numberA number for the opacity of the shadow. Refer to shadow-intensity in the <model-viewer> documentation.
shadowSoftness?numberA number for the bluriness of the shadow. Refer to shadow-softness in the <model-viewer> documentation.
animationName?stringA string of the animation to play by name. Refer to animation-name in the <model-viewer> documentation.
animationCrossfadeDuration?stringA string of the animation crossfade duration between the previous and next animations. Refer to animation-cross-fade-duration in the <model-viewer> documentation.
autoplay?booleanA boolean to enable the model animations. Refer to autoplay in the <model-viewer> documentation.
variantName?stringA string to select a model variant by name. Refer to variant-name in the <model-viewer> documentation.
orientation?stringA string to rotate the model. Refer to orientation in the <model-viewer> documentation.
scale?stringA string to scale the model. Refer to scale in the <model-viewer> documentation.
onError?(event: Event) => voidThe callback to invoke when the 'error' event is triggered. Refer to error in the <model-viewer> documentation.
onLoad?(event: Event) => voidThe callback to invoke when the load event is triggered. Refer to load in the <model-viewer> documentation.
onPreload?(event: Event) => voidThe callback to invoke when the 'preload' event is triggered. Refer to preload in the <model-viewer> documentation.
onModelVisibility?(event: Event) => voidThe callback to invoke when the 'model-visibility' event is triggered. Refer to model-visibility in the <model-viewer> documentation.
onProgress?(event: Event) => voidThe callback to invoke when the 'progress' event is triggered. Refer to progress in the <model-viewer> documentation.
onArStatus?(event: Event) => voidThe callback to invoke when the 'ar-status' event is triggered. Refer to ar-status in the <model-viewer> documentation.
onArTracking?(event: Event) => voidThe callback to invoke when the 'ar-tracking' event is triggered. Refer to ar-tracking in the <model-viewer> documentation.
onQuickLookButtonTapped?(event: Event) => voidThe callback to invoke when the 'quick-look-button-tapped' event is triggered. Refer to quick-look-button-tapped in the <model-viewer> documentation.
onCameraChange?(event: Event) => voidThe callback to invoke when the 'camera-change' event is triggered. Refer to camera-change in the <model-viewer> documentation.
onEnvironmentChange?(event: Event) => voidThe callback to invoke when the 'environment-change' event is triggered. Refer to environment-change in the <model-viewer> documentation.
onPlay?(event: Event) => voidThe callback to invoke when the 'play' event is triggered. Refer to play in the <model-viewer> documentation.
onPause?(event: Event) => voidThe callback to invoke when the 'pause' event is triggered. Refer to pause in the <model-viewer> documentation.
onSceneGraphReady?(event: Event) => voidThe callback to invoke when the 'scene-graph-ready' event is triggered. Refer to scene-graph-ready in the <model-viewer> documentation.

Required fields​

The ModelViewer component requires the following fields from the Storefront API's Model3d object:

{
  alt
  sources {
    url
  }
}

Component type​

The ModelViewer component is a client component, which means that it renders on the client. For more information about component types, refer to React Server Components.