---
id: v4
title: v4.x
---

## MapillaryJS `v4.x` Migration Guide

This page describes how to migrate from MapillaryJS `v3.x` to MapillaryJS `v4.x`.

## General

- Github differential - [v3.1.0...v4.0.0-beta.6](https://github.com/mapillary/mapillary-js/compare/v3.1.0...v4.0.0-beta.6)
- Properties named `key` in `v3.x` have been renamed to `id` throughout the library in `v4.x`

### Distribution

#### Renamed Files

| `v3.x`              | `v4.x`                    |
| ------------------- | ------------------------- |
| `mapillary.min.js`  | `mapillary.js`            |
| `mapillary.js`      | `mapillary.unminified.js` |
| `mapillary.min.css` | `mapillary.css`           |

## Module

All namespacing has been removed and the global UMD name has been changed.

### Global UMD Name

| `v3.x`      | `v4.x`      |
| ----------- | ----------- |
| `Mapillary` | `mapillary` |

### Import

#### `v3.x`

```js
import * as Mapillary from 'mapillary-js';

const viewer = new Mapillary.Viewer({...});
const marker = new Mapillary.MarkerComponent.SimpleMarker({...});
const popup = new Mapillary.PopupComponent.Popup({...});
```

#### `v4.x`

```js
import { Popup, SimpleMarker, Viewer } from 'mapillary-js';

const viewer = new Viewer({...});
const marker = new SimpleMarker({...});
const popup = new Popup({...});
```

### Destruct

#### `v3.x`

```js
const viewer = new Mapillary.Viewer({...});
const marker = new Mapillary.MarkerComponent.SimpleMarker({...});
const popup = new Mapillary.PopupComponent.Popup({...});
```

#### `v4.x`

```js
const { Popup, SimpleMarker, Viewer } = mapillary;

const viewer = new Viewer({...});
const marker = new SimpleMarker({...});
const popup = new Popup({...});
```

### Styles

All style classes have been renamed.

## Viewer

### Methods

#### Renamed

| `v3.x` | `v4.x` | Description |
| --- | --- | --- |
| `setUserToken` | `setAccessToken` | Now accepts a client access token or a user access token |

### Options

#### Added

- `trackResize` - **Breaking change:** the viewer now tracks browser window resizing by default. Set this option to false if you want to handle viewer resizing with custom logic.
- `dataProvider` - Override the default data provider.

#### Removed

| `v3.x`             | `v4.x`                                          |
| ------------------ | ----------------------------------------------- |
| `baseImageSize`    | No replacement                                  |
| `basePanoramaSize` | No replacement                                  |
| `baseImageSize`    | No replacement                                  |
| `maxImageSize`     | No replacement                                  |
| `apiClient`        | Use `dataProvider` and/or `accessToken` instead |

#### Renamed

| `v3.x`      | `v4.x`        |
| ----------- | ------------- |
| `imageKey`  | `imageId`     |
| `userToken` | `accessToken` |

### Component Options

#### Removed

| `v3.x`       | `v4.x`         |
| ------------ | -------------- |
| `background` | No replacement |
| `debug`      | No replacement |
| `route`      | No replacement |

#### Renamed

| `v3.x`        | `v4.x`    |
| ------------- | --------- |
| `imagePlane`  | `image`   |
| `mouse`       | `pointer` |
| `spatialData` | `spatial` |

#### Replaced

| `v3.x`       | `v4.x`                      |
| ------------ | --------------------------- |
| `image`      | Moved to `fallback` options |
| `navigation` | Moved to `fallback` options |

### Events

Event names are not provided as static properties on the Viewer class.

| `v3.x`                                    | `v4.x`                     |
| ----------------------------------------- | -------------------------- |
| `viewer.on(Mapillary.Viewer.click, ...);` | `viewer.on('click', ...);` |

#### Contracts

All emitted events are now an object with the following properties populated:

- `type` - Event type
- `target` - Instance that emitted the event

Additional properties are provided per event type.

#### Renamed Event Types

| `v3.x`                 | `v4.x`          |
| ---------------------- | --------------- |
| `bearingchanged`       | `bearing`       |
| `fovchanged`           | `fov`           |
| `loading`              | `dataloading`   |
| `navigablechanged`     | `navigable`     |
| `nodechanged`          | `image`         |
| `positionchanged`      | `position`      |
| `povchanged`           | `pov`           |
| `removed`              | `remove`        |
| `sequenceedgeschanged` | `sequenceedges` |
| `spatialedgeschanged`  | `spatialedges`  |

## Image

The `Node` class has been renamed to `Image`.

### Properties

#### Removed

| `v3.x`         | `v4.x`                   |
| -------------- | ------------------------ |
| `cameraUuid`   | No replacement           |
| `fullPano`     | Use `cameraType` instead |
| `gpano`        | Use `cameraType` instead |
| `pano`         | Use `cameraType` instead |
| `mergeVersion` | No replacement           |
| `projectKey`   | No replacement           |

#### Renamed

| `v3.x`                 | `v4.x`                 |
| ---------------------- | ---------------------- |
| `alt`                  | `computedAltitude`     |
| `ca`                   | `compassAngle`         |
| `cameraProjectionType` | `cameraType`           |
| `clusterKey`           | `clusterId`            |
| `computedCA`           | `computedCompassAngle` |
| `computedLatLon`       | `computedLngLat`       |
| `key`                  | `id`                   |
| `latLon`               | `lngLat`               |
| `mergeCC`              | `mergeId`              |
| `organizationKey`      | `ownerId`              |
| `orientation`          | `exifOrientation`      |
| `originalAlt`          | `originalAltitude`     |
| `originalCA`           | `originalCompassAngle` |
| `originalLatLon`       | `originalLngLat`       |
| `sequenceKey`          | `sequenceId`           |
| `userKey`              | `creatorId`            |
| `userName`             | `creatorName`          |

#### Replaced

| `v3.x`            | `v4.x`             |
| ----------------- | ------------------ |
| `focal, ck1, ck2` | `cameraParameters` |

## Types

| `v3.x` | `v4.x` |
| --- | --- |
| `ILatLon`: `{ lat: number, lon: number }` | `LngLat`: `{ lat: number, lng: number }` |
| `ILatLonAlt`: `{ alt: number, lat: number, lon: number }` | `LngLatAlt`: `{ alt: number, lat: number, lng: number }` |
| `AbortMapillaryError` | `CancelMapillaryError` |

## Enums

#### Renamed

| `v3.x`          | `v4.x`                |
| --------------- | --------------------- |
| `EdgeDirection` | `NavigationDirection` |

## Component

### Components

#### Removed

| `v3.x`       | `v4.x`                                                    |
| ------------ | --------------------------------------------------------- |
| `background` | No replacement                                            |
| `debug`      | No replacement                                            |
| `route`      | Use the custom render API or custom HTML elements instead |

#### Renamed

| `v3.x`        | `v4.x`               |
| ------------- | -------------------- |
| `imageplane`  | `image`              |
| `spatialdata` | `spatial`            |
| `image`       | `imagefallback`      |
| `navigation`  | `navigationfallback` |

### Events

| `v3.x`                                | `v4.x`            |
| ------------------------------------- | ----------------- |
| `MarkerComponent.dragend`             | `markerdragend`   |
| `MarkerComponent.dragstart`           | `markerdragstart` |
| `MarkerComponent.changed`             | `markerposition`  |
| `MarkerComponent.hoveredkeychanged`   | `hover`           |
| `SequenceComponent.hoveredkeychanged` | `hover`           |
| `SequenceComponent.playingchanged`    | `playing`         |
| `TagComponenent.geometrycreated`      | `geometrycreate`  |
| `TagComponenent.creategeometryend`    | `tagcreateend`    |
| `TagComponenent.creategeometrystart`  | `tagcreatestart`  |
| `TagComponenent.modechanged`          | `tagmode`         |
| `TagComponenent.tagschanged`          | `tags`            |
| `Tag.click`                           | `click`           |
| `Tag.geometrychanged`                 | `geometry`        |
| `Tag.changed`                         | `tag`             |

## Interaction

#### Removed

| `v3.x`                           | `v4.x`         |
| -------------------------------- | -------------- |
| `MouseComponent#doubleClickZoom` | No replacement |

## API

The complete API functionality, including ents, contracts, and providers, has been replaced. See the [v4 API reference](/api/modules/api) and examples for info about the new functionality.