⚠️ Note that the Matterport Web Component is currently in public beta - interface and syntax are subject to change. ⚠️ Please email [email protected] with any suggestions or questions.

See here for full documentation, or keep reading for quick instructions.

Installation

Run these commands in your project:

yarn add @matterport/webcomponent

# replace `public` with your static assets directory (static, public, etc)
# this copies the required assets to your project
yarn matterport-assets YOUR_ASSET_DIRECTORY

# npm is also supported:
npm install @matterport/webcomponent
# if using npm, use `npx` next:
npx matterport-assets YOUR_ASSET_DIRECTORY

You must also add the current compatible version of "three" as a dependency in your app:

yarn add [email protected]

Then import @matterport/webcomponent somewhere in your source:

import '@matterport/webcomponent'

To use, add a <matterport-viewer> component with a model ID as the m attribute:

<matterport-viewer m="SxQL3iGyoDo"></matterport-viewer>

If you used any nested directories when running the matterport-assets command, set the asset-base attribute to match:

<!-- if you ran `yarn matterport-assets foo/bar`, use: -->
<matterport-viewer m="SxQL3iGyoDo" asset-base="bar"></matterport-viewer>

<!-- if you ran `yarn matterport-assets foo/bar/baz`, use: -->
<matterport-viewer m="SxQL3iGyoDo" asset-base="bar/baz"></matterport-viewer>

<!-- if you ran `yarn matterport-assets foo`, no asset-base attribute is needed: -->
<matterport-viewer m="SxQL3iGyoDo"></matterport-viewer>

You can add any URL param as an attribute:

<matterport-viewer m="SxQL3iGyoDo" qs="1" brand="0"></matterport-viewer>

If a URL param is camelCase, switch it to kebab-case:

<!-- `applicationKey` becomes `application-key` -->
<matterport-viewer m="SxQL3iGyoDo" application-key="YOUR_APPLICATION_KEY"></matterport-viewer>

For users familiar with the previous version of the bundle that required an iframe, you can use a src attribute and provide the same URL that you would for that iframe:

<!-- using the full URL or path will work: -->
<matterport-viewer src="/bundle/showcase.html?m=SxQL3iGyoDo&applicationKey=YOUR_APPLICATION_KEY"></matterport-viewer>

<!-- as will using just the query string: -->
<matterport-viewer src="m=SxQL3iGyoDo&applicationKey=YOUR_APPLICATION_KEY"></matterport-viewer>

(Note that in the first method with the full path, nothing is actually loaded from /bundle/showcase.html - anything that isn't the query string is ignored. The full path is allowed to support easy transition from <iframe> to <matterport-viewer> components.)

Caveats

Workspaces

In projects with Yarn workspaces, it may be helpful to mark the SDK package as nohoist if you run into issues with yarn matterport-assets copying the assets correctly. For example:

In my project, I have two workspaces, a and b. Both use the @matterport/webcomponent package.

Problem: Installing in both locations would hoist @matterport/webcomponent to the root directory, and yarn workspace a matterport-assets may run into issues.

Solution: In my root directory's package.json, I add the following:

...
  "workspaces": [
    ...,
    "nohoist": [
      "**/@matterport/webcomponent"
      ...
    ]
  ]
...

I then delete all node_modules folders in my project and reinstall with yarn install. From there, I can run yarn workspace a matterport-assets public and see the assets copied to packages/a/public.