---
id: try
title: Try MapillaryJS
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::info You will learn

- How to install MapillaryJS
- How to add MapillaryJS to your website

:::

## Installation

MapillaryJS is essentially an [npm package](https://www.npmjs.com/package/mapillary-js) that can be installed via [Yarn](https://classic.yarnpkg.com) or [npm](https://docs.npmjs.com/about-npm).

### Prerequisites

For this guide, the following is required.

- You have [Node](https://nodejs.org) installed at `version >= v12.3.0`.
- You have [Yarn](https://classic.yarnpkg.com) installed at `version >= v1.22.0`.

To start using MapillaryJS with data from the [Mapillary](https://www.mapillary.com) platform, you need [register an application](https://www.mapillary.com/dashboard/developers) to get a [client access token](https://mapillary.com/developer/api-documentation). When [extending MapillaryJS](/docs/extension/extend) to provide your own data, no access token is needed.

Once you have setup the prerequisites, you can try MapillaryJS in your own website.

## Add MapillaryJS to a Website

### Using a Module Bundler

Install the package.

<Tabs
  defaultValue='yarn'
  values={[
    { label: 'Yarn', value: 'yarn', },
    { label: 'npm', value: 'npm', },
  ]
}>
<TabItem value='yarn'>

```zsh
yarn add mapillary-js@next
```

</TabItem>
<TabItem value='npm'>

```zsh
npm install --save mapillary-js@next
```

</TabItem>
</Tabs>

Use a CSS loader or include the CSS file in the `<head>` of your HTML file.

```html
<link
  href="https://unpkg.com/mapillary-js@4.0.0-beta.6/dist/mapillary.css"
  rel="stylesheet"
/>
```

Include the following code in your application. If you are developing a TypeScript application you will get code editor intellisense while typing.

<Tabs
  defaultValue='ts'
  values={[
    { label: 'TypeScript', value: 'ts', },
    { label: 'JavaScript', value: 'js', },
  ]
}>
<TabItem value='ts'>

```ts
import {Viewer, ViewerOptions} from 'mapillary-js';

const container = document.createElement('div');
container.style.width = '400px';
container.style.height = '300px';
document.body.appendChild(container);

const options: ViewerOptions = {
  accessToken: '<your access token>',
  container,
  imageId: '<your image ID for initializing the viewer>',
};
const viewer = new Viewer(options);
```

</TabItem>
<TabItem value='js'>

```js
import {Viewer} from 'mapillary-js';

const container = document.createElement('div');
container.style.width = '400px';
container.style.height = '300px';
document.body.appendChild(container);

const viewer = new Viewer({
  accessToken: '<your access token>',
  container,
  imageId: '<your image ID for initializing the viewer>',
});
```

</TabItem>
</Tabs>

### Using a CDN

Include the JavaScript and CSS files in the `<head>` of your HTML file.

```html
<script src="https://unpkg.com/mapillary-js@4.0.0-beta.6/dist/mapillary.js"></script>
<link
  href="https://unpkg.com/mapillary-js@4.0.0-beta.6/dist/mapillary.css"
  rel="stylesheet"
/>
```

Add a container to the `<body>` of your HTML file.

```html
<div id="mly" style="width: 400px; height: 300px;"></div>
```

The global [UMD](https://github.com/umdjs/umd) name for MapillaryJS is `mapillary`. Include the following script in the `<body>` of your HTML file.

```html
<script>
  var {Viewer} = mapillary;

  var viewer = new Viewer({
    accessToken: '<your access token>',
    container: 'mly', // the ID of our container defined in the HTML body
    imageId: '<your image ID for initializing the viewer>',
  });
</script>
```

## That's It!

Congratulations! You have just added MapillaryJS to your project.

You should see something similar to what is shown in the live editor below.

:::note

Throughout the documentation the live example editors use the [React library](https://reactjs.org/) and the [JSX syntax](https://reactjs.org/docs/introducing-jsx.html). This is the first such example that you will see. If you have not used React before, that is no problem, understanding React and JSX is not needed to follow along in the guides.

:::

:::tip

You can edit the code and get immediate feedback in the **Result** section.

:::

```jsx live
function renderMapillary(props) {
  class ViewerComponent extends React.Component {
    constructor(props) {
      super(props);
      this.containerRef = React.createRef();
    }

    componentDidMount() {
      this.viewer = new Viewer({
        accessToken: this.props.accessToken,
        container: this.containerRef.current,
        imageId: this.props.imageId,
      });
    }

    componentWillUnmount() {
      if (this.viewer) {
        this.viewer.remove();
      }
    }

    render() {
      return <div ref={this.containerRef} style={this.props.style} />;
    }
  }

  return (
    <ViewerComponent
      accessToken={accessToken}
      imageId={'498763468214164'}
      style={{width: '100%', height: '300px'}}
    />
  );
}
```

## Recap

- Install MapillaryJS with Yarn or npm, or use a CDN
- Use a CSS loader or include the CSS file in the `<head>` of your HTML file
- Import the Viewer class and create a new Viewer instance with your options

## Next steps

Now you are ready to start exploring the [guide to main concepts](/docs/guides).
