# Loading the latest version of MapKit JS Link to the most recent autoupdating version of MapKit JS, or a version of your choice. ## Overview When you include a map element on your webpage, your webpage loads a version of MapKit JS. Load the most recent version of MapKit JS available whenever possible. Load MapKit JS directly using a ` ``` See [Creating a Maps token](/documentation/MapKitJS/creating-a-maps-token) to obtain a Maps token and insert the token into the `data-token` attribute. To load MapKit JS more efficiently, specify that MapKit JS only loads the specific libraries that you need by setting the `data-libraries` attribute. Once the callback triggers, `mapkit` is available as a global object. Install `@types/apple-mapkit` separately to access its type definitions. ### Select script element attributes The `script` tag you use to load MapKit JS supports several attribute elements that allow you to customize the loading of the framework to support only the features you need. ```html ``` In this example, MapKit JS self-initializes and self-loads the specified libraries, and then triggers the callback when loading of the libraries is complete. You can choose the MapKit JS interfaces and features by changing the libraries to load. The script tag value is the URL that points to `mapkit.core.js`, the principal JavaScript file for MapKit JS, for all versions of the src attribute of this script tag. The `script` tag, and all the examples here, include two additional attributes recommended for use with MapKit JS: - `crossorigin`: Short for `crossorigin="anonymous"`, this attribute instructs the browser to connect to the MapKit JS CDN using anonymous credentials mode. This improves performance by allowing subsequent MapKit JS network requests to reuse the same HTTP/2 connection. - `async`: With this attribute, the browser evaluates the script as soon as it downloads it. This prevents `mapkit.core.js` from blocking the page load, and initializes and loads the MapKit JS libraries as soon as possible. Your app needs to wait for the callback function execution before interacting with the API. The data attributes you can set on the `script` element are: - `data-callback`: Required; this is the callback the browser calls when MapKit JS finishes loading or when library loading fails, allowing your application to handle errors. - `data-language`: The language to set for MapKit JS. A language ID is a language designator followed by an optional region or script designator. Examples of language IDs include: `de` (German), `es-MX`, (Mexican Spanish), and `zh-Hans` (simplified Chinese). - `data-libraries`: Required; this is a comma-separated list of libraries to load at initialization. See the list of available libraries and the services they provide below. - `data-token`: Required unless you intend to call [`init()`](/documentation/MapKitJS/mapkit/init) later. See [Creating a Maps token](/documentation/MapKitJS/creating-a-maps-token) to obtain a Maps token. ## Choose specific releases using semantic versioning MapKit JS follows semantic versioning with each release. As a result, you have full control over when to upgrade to a new version of MapKit JS. Each version follows the standard semantic versioning pattern `MAJOR.MINOR.PATCH,` which conveys the following information: - `MAJOR`: Incompatible API changes - `MINOR`: New functionality, but backward-compatible - `PATCH`: Backward-compatible bug fixes A backward-compatible new release that contains only bug fixes increases the patch version; a backward-compatible new release that contains new features or functionality increases the minor version. A new release that changes the API, so it’s no longer backward-compatible, increases the major version. In the following example, the script tag pins the major version at `6`, and the server automatically selects the latest `minor.patch` version: ```html ``` It’s also possible to request more specific versions by specifying the minor version, as the following example shows: ```html ``` Here, the script tag pins the `major.minor` version at `6.0`, and the server automatically selects the latest patch version. Autoupdate URLs have a cache time of 5 minutes. ## Use explicitly versioned URLs If your code depends upon a specific MapKit JS version, each version of MapKit JS has a unique URL. Linking to a specific version ensures that your app always gets that exact version of MapKit JS. MapKit JS Loader provides a `version` options property for setting the desired version. Below is an example of a version URL, loading MapKit JS with a ` ``` Browsers cache version URLs for a longer time. Use versioned URLs if you want to be in full control of when MapKit JS updates and get the benefits of browser caching. ## Load the full bundle of MapKit JS > Note: > The full bundle does not contain newer features like ``doc://com.apple.mapkitjs/documentation/MapKitJS/LookAround``. A full browser bundle is also available, but it isn’t recommended in production for performance reasons. With the full bundle, the full MapKit JS interfaces are available as soon as the script tag loads. ```javascript ``` This example uses the `defer` attribute in place of `async`. With this attribute, the browser evaluates the script only after the browser fully downloads and parses the HTML. This prevents `mapkit.js` from blocking the page load, but the `mapkit` instance isn’t available to the embedded ` ``` The following sample is a JavaScript example for loading MapKit JS dynamically: ```javascript // This promise resolves when MapKit JS downloads and evaluates. const mapKitJsLoadedPromise = new Promise(resolve => { const element = document.createElement("script"); element.addEventListener("load", resolve, { once : true }); element.nonce = "{nonce-value}"; element.src = "https://cdn.apple-mapkit.com/mk/x/mapkit.js" element.crossOrigin = "anonymous"; document.head.appendChild(element); }); ``` --- Copyright © 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)