How to use United States vector basemaps in your web app

Esri recently published a new set of custom basemaps for the United States. These basemaps include updated place names recently defined by the U.S. Government, as well as updated treatments of several disputed boundaries and places previously defined by the U.S. State Department. If you are interested in learning about how to update your organizational settings and content in ArcGIS Online or ArcGIS Enterprise to use Esri’s United States vector basemaps, review Esri Vector Basemaps for United States. This blog walks through the code required to use these basemaps in new or existing apps built with ArcGIS Maps SDK for JavaScript or one of Esri’s supported open source mapping libraries.

Using the US vector basemaps with ArcGIS Maps SDK for JavaScript

The SDK provides a number of ways in which you can use a particular basemap in our app:

Configure the basemap you want in the web map or web scene. If you follow the guidance in the Esri Vector Basemaps for United States blog for using a basemap with the US world view, you can simply reference this webmap in your code. If you are updating an existing webmap that was already used in your app, no code changes are required (this is the beauty of building apps with web maps/web scenes!).

Set the basemap directly in code. There are essentially two options for accomplishing this:

1. Use the basemap styles service. The ArcGIS Basemap Styles service is a location service that serves vector and image tiles for the world. It can display localized language place labels, places, and worldviews. It also supports accessing custom basemap styles. Worldviews can be set using the BasemapStyle class, which defines the style of the basemap from the basemap style service (v2). Using this service requires that your end users authenticate with their ArcGIS account, or you use an API key in your app. See the Security and authentication guide to learn about implementation details.

// Display the Community basemap with the United States worldview
const basemap = new Basemap({
  style: new BasemapStyle({
    id: "arcgis/community",
    worldview: "unitedStatesOfAmerica"
  })
});

Here is a sample app showing how you can set the worldview parameter to get the basemap with a particular worldview.

Note: The worldview property on the BasemapStyle class was added to the SDK at version 4.29. If you are using an earlier version of the SDK, you can still access the basemap styles service in two ways:

(a) VectorTileLayer with custom parameters: You can access the basemap styles service directly from the vector tile style URL, using the customParameters to set the worldview parameter. Available since version 4.22.

// create a VectorTileLayer from a style URL
const mapBaseLayer = new VectorTileLayer({
  url: "https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/arcgis/topographic",
  // set the worldview as a custom parameter
  customParameters: {
    worldview: "unitedStatesOfAmerica"
  },
});

const basemap = new Basemap({
  // set the VTL as the basemap layer
  baseLayers: [mapBaseLayer]
});

(b) Request interceptors. In the esriConfig class, set request.interceptors to modify requests before or after they are sent. This allows you to append the worldview parameter whenever a request is made to the basemap styles service. Available since version 4.8.

2. Use the Basemap class to reference a US style directly from a WebMap or VectorTileLayer. Basemaps can be created from a WebMap portal item ID:

// Create a basemap from a WebMap portal item ID
const basemap = new Basemap({
  portalItem: {
    id: "668f436dc2dc4f2c83ceb0c064380590" // Topo (US worldview)
  }
});

Or set the Basemap’s baseLayers from a VectorTileLayer style URL or portalItem:

// create a VectorTileLayer from a style URL or portal item
const mapBaseLayer = new VectorTileLayer({
  // Topographic style with US worldview
  url: "https://www.arcgis.com/sharing/rest/content/items/27e89eb03c1e4341a1d75e597f0291e6/resources/styles/root.json"
});

const basemap = new Basemap({
  // set the VTL as the basemap layer
  baseLayers: [mapBaseLayer]
});

Basemap Gallery and Basemap Toggle components

If your app uses the Basemap Gallery or Basemap Toggle components (or widgets), validate that they are using the US vector basemaps.

Basemap Gallery: If your app uses ArcGIS logins or a global API key, the gallery is configured automatically using your portal settings:

• Region: If the region is set to United States and the basemap gallery setting is “Esri default,” no action is needed
• Basemap gallery: if you have already configured your gallery to use US basemaps, no action is needed

If your app has anonymous end users (no ArcGIS login), by default, the basemap gallery is based on the “world” worldview. You must update the basemap gallery’s source property with the US basemaps that you want to use. This can be done by setting the source to use the United States Vector Basemaps group (like the code below), or by setting the source property to a list of hand-selected US basemaps that you want to use.

// get the basemap gallery element
const basemapGallery = document.querySelector("arcgis-basemap-gallery");
// change the default source
basemapGallery.source =  new PortalBasemapsSource({
  query: {
    // United States Vector Basemaps group
    id: "68efc5ce1e0b43cb819f7bba4a6bd7ea"
  }
});

Basemap Toggle: This component works by toggling between an “active basemap” and the “next basemap.” Both properties are of type Basemap so you can define the Basemap in one of the ways described above.

Using the US vector basemaps with Esri Leaflet

Use the basemap styles service, specify the style you want, and set the worldview parameter of Esri Leaflet Vector to change the political worldview of the basemap layer.

See the Change the basemap worldview sample.

Using the US vector basemaps with MapLibre

Use the basemap styles service, specify the style you want, and set the worldview parameter to “unitedStatesOfAmerica”.

See the Change the basemap style sample to see how the service is used and style options are applied. Note that in addition to the code in this sample, you must also set the worldview parameter.

Using the US vector basemaps with OpenLayers

Use the basemap styles service, specify the style you want, and set the worldview parameter to “unitedStatesOfAmerica”.

See the Change the basemap style sample to see how the service is used and style options are applied. Note that in addition to the code in this sample, you must also set the worldview parameter.

Using the US vector basemaps with Cesium

Cesium doesn’t support vector tile layers so the recommended option is to use Esri’s static basemap tiles service, which provides raster tiles. At the time of writing, the worldview parameter is not yet available with this service offering, but is planned for April 2025. You can update your code (today) to reference the “unitedStatesOfAmerica” worldview and once the service accepts this parameter, the basemap will show the US worldview.

See the How to add ArcGIS base layers sample for how to use static basemap tiles.

Using the US vector basemaps in configurable apps and builders

ArcGIS Experience Builder: Apps built with Experience Builder usually require minimal updates since they reference web maps and web scenes which can be updated to use the Esri Vector Basemaps for United States. Experience Builder will read the basemap gallery setting in your Online or Enterprise organization to populate the Basemap Gallery widget, so if you have set that up to use the US basemaps, no further action is needed. You can also configure custom basemaps in Experience Builder, so if you have done that you should make sure that the basemaps you’ve selected are using the US worldview.

ArcGIS Instant Apps: Apps built with Instant Apps usually require minimal updates since they reference web maps and web scenes which can be updated to use the Esri Vector Basemaps for United States. However, some Instant Apps have Basemap Gallery, Locator Map, and/or Basemap Toggle tools available in the configuration options. If your app has one or all of those tools, you should verify that they are referencing the US basemaps. To update the app to use the US basemap, go back into the Instant App configuration experience and select the appropriate basemap. For convenience, you can use the Esri Vector Basemaps for United States Item ID Chart PDF to find the item ID of the basemap you want to use, and search for it in the basemap picker configuration UI.

Please refer to this Instant App Capabilities Matrix to help you identify which Instant Apps might need to be updated.

Conclusion

As described above, there are multiple approaches for using vector basemaps for United States in your app. For additional information on using Esri’s vector tile basemaps in your application, see Esri Developer, and ArcGIS Maps SDK for JavaScript documentation.