<!--
{
  "documentType" : "article",
  "framework" : "MapKitJS",
  "identifier" : "/documentation/MapKitJS/handling-initialization-events",
  "metadataVersion" : "0.1.0",
  "role" : "collectionGroup",
  "title" : "Handling initialization events"
}
-->

# Handling initialization events

Respond to events that trigger when MapKit JS initializes.

## Discussion

Unless you wish to explicitly control initialization timing in JavaScript, use `data-token` instead of handling initialization events directly. See [Loading the latest version of MapKit JS](/documentation/MapKitJS/loading-the-latest-version-of-mapkit-js) for more information.

The `mapkit` object emits two events to indicate the success or failure of a configuration operation. The initialization process configures MapKit JS. In addition, there are two events indicate the success or failure of a batch of library loads.

|Event                 |Interface                                                                         |Summary                                                                                 |
|----------------------|----------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
|`configuration-change`|``doc://com.apple.mapkitjs/documentation/MapKitJS/MapKitConfigurationChangeEvent``|The MapKit configuration changes due to either a successful initialization or a refresh.|
|`error`               |``doc://com.apple.mapkitjs/documentation/MapKitJS/MapKitConfigurationErrorEvent`` |MapKit fails to initialize.                                                             |
|`load`                |``doc://com.apple.mapkitjs/documentation/MapKitJS/MapKitLibraryLoadEvent``        |A batch of libraries loads.                                                             |
|`load-error`          |``doc://com.apple.mapkitjs/documentation/MapKitJS/MapKitLibraryLoadEvent``        |A batch of libraries fails to load.                                                     |

MapKit JS invokes these events asynchronously upon success or failure of the initialization request. The example below shows a common use case:

```javascript
mapkit.init({ authorizationCallback: function(done) { done("your-token"); }, ... });
mapkit.addEventListener("configuration-change", function(event) {
    switch (event.status) {
    case "Initialized":
        // MapKit JS initializes and configures.
        break;
    case "Refreshed":
        // The MapKit JS configuration updates.
        break;
    }
});
```

## Topics

### Events

[`MapKitConfigurationChangeEvent`](/documentation/MapKitJS/MapKitConfigurationChangeEvent)

An event that represents a configuration change.

[`MapKitConfigurationErrorEvent`](/documentation/MapKitJS/MapKitConfigurationErrorEvent)

An event that represents a configuration error.

[`MapKitLibraryLoadEvent`](/documentation/MapKitJS/MapKitLibraryLoadEvent)

An event that occurs when the MapKit JS library is loaded or fails loading.

### Initialization and error status

[`ConfigurationChangeStatus`](/documentation/MapKitJS/ConfigurationChangeStatus)

Values that represent the status of a configuration change.

[`ConfigurationErrorStatus`](/documentation/MapKitJS/ConfigurationErrorStatus)

A value that represents the status of a configuration error.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)