{"id":2716872,"date":"2025-03-06T06:43:53","date_gmt":"2025-03-06T14:43:53","guid":{"rendered":"https:\/\/www.esri.com\/arcgis-blog\/?post_type=blog&p=2716872"},"modified":"2025-03-06T11:09:43","modified_gmt":"2025-03-06T19:09:43","slug":"how-to-use-a-basemap-with-a-specific-world-view-in-your-web-app","status":"publish","type":"blog","link":"https:\/\/www.esri.com\/arcgis-blog\/products\/js-api-arcgis\/developers\/how-to-use-a-basemap-with-a-specific-world-view-in-your-web-app","title":{"rendered":"How to use United States vector basemaps in your web app"},"author":4271,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","format":"standard","meta":{"_acf_changed":false,"_searchwp_excluded":""},"categories":[738191],"tags":[42301,769562,42641,33981,762062],"industry":[],"product":[36831,36601],"class_list":["post-2716872","blog","type-blog","status-publish","format-standard","hentry","category-developers","tag-arcgis-enterprise","tag-arcgis-maps-sdk-for-javascript","tag-arcgis-online","tag-united-states","tag-vector-basemap","product-js-api-arcgis","product-developers"],"acf":{"short_description":"Use basemaps that have a specific world view (such as a US world view) in your apps - whether you have a new app or are updating an existing one.","flexible_content":[{"acf_fc_layout":"content","content":"

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<\/a> or ArcGIS Enterprise<\/a> to use Esri’s United States vector basemaps, review Esri Vector Basemaps for United States<\/a>. 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.<\/p>\n

Using the US vector basemaps with ArcGIS Maps SDK for JavaScript<\/h2>\n

The SDK provides a number of ways in which you can use a particular basemap in our app:<\/p>\n

Configure the basemap you want in the web map or web scene.<\/strong> If you follow the guidance in the Esri Vector Basemaps for United States blog<\/a> 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!).<\/p>\n

Set the basemap directly in code.<\/strong> There are essentially two options for accomplishing this:<\/p>\n

    \n
  1. Use the basemap styles service<\/a><\/strong>. 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\u00a0basemap styles. Worldviews can be set using the\u00a0BasemapStyle<\/a>\u00a0class, which defines the style of the basemap from the basemap style service (v2)<\/a>. 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<\/a> guide to learn about implementation details.<\/li>\n<\/ol>\n"},{"acf_fc_layout":"content","content":"
    \/\/ Display the Community basemap with the United States worldview<\/span>\r\nconst<\/span> basemap = new<\/span> Basemap<\/span>({\r\n  style<\/span>: new<\/span> BasemapStyle<\/span>({\r\n    id<\/span>: \"arcgis\/community\"<\/span>,\r\n    worldview<\/span>: \"unitedStatesOfAmerica\"<\/span>\r\n  })\r\n});\r\n<\/code><\/pre>\n"},{"acf_fc_layout":"content","content":"
    Note:<\/strong> The worldview<\/code><\/a> property on the BasemapStyle<\/a> 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<\/a> in two ways:<\/p>\n
    (a) VectorTileLayer with custom parameters:\u00a0You can access the basemap styles service<\/a> directly from the vector tile style URL, using the customParameters<\/code><\/a> to set the worldview<\/code><\/a> parameter.\u00a0Available since version 4.22.<\/em><\/p>\n
    \/\/ create a VectorTileLayer from a style URL<\/span>\r\nconst<\/span> mapBaseLayer = new<\/span> VectorTileLayer<\/span>({\r\n  url<\/span>: \"https:\/\/basemapstyles-api.arcgis.com\/arcgis\/rest\/services\/styles\/v2\/styles\/arcgis\/topographic\"<\/span>,\r\n  \/\/ set the worldview as a custom parameter<\/span>\r\n  customParameters<\/span>: {\r\n    worldview<\/span>: \"unitedStatesOfAmerica\"<\/span>\r\n  },\r\n});\r\n\r\nconst<\/span> basemap = new<\/span> Basemap<\/span>({\r\n  \/\/ set the VTL as the basemap layer<\/span>\r\n  baseLayers<\/span>: [mapBaseLayer]\r\n});\r\n<\/code><\/pre>\n
    2. Use the Basemap<\/a> class to reference a US style<\/strong> directly from a WebMap or VectorTileLayer. Basemaps can be created from a WebMap portal item ID:<\/p>\n"},{"acf_fc_layout":"content","content":"
    \/\/ Create a basemap from a WebMap portal item ID<\/span>\r\nconst<\/span> basemap = new<\/span> Basemap<\/span>({\r\n  portalItem<\/span>: {\r\n    id<\/span>: \"668f436dc2dc4f2c83ceb0c064380590<\/span>\"<\/span> \/\/ Topo (US worldview)<\/span>\r\n  }\r\n});\r\n<\/code><\/pre>\n"},{"acf_fc_layout":"content","content":"
    Or set the Basemap’s baseLayers<\/code> from a VectorTileLayer style URL or portalItem:<\/p>\n"},{"acf_fc_layout":"content","content":"
    \/\/ create a VectorTileLayer from a style URL or portal item<\/span>\r\nconst<\/span> mapBaseLayer = new<\/span> VectorTileLayer<\/span>({\r\n  \/\/ Topographic style with US worldview<\/span>\r\n  url<\/span>: \"https:\/\/www.arcgis.com\/sharing\/rest\/content\/items\/27e89eb03c1e4341a1d75e597f0291e6\/resources\/styles\/root.json\"<\/span>\r\n});\r\n\r\nconst<\/span> basemap = new<\/span> Basemap<\/span>({\r\n  \/\/ set the VTL as the basemap layer<\/span>\r\n  baseLayers<\/span>: [mapBaseLayer]\r\n});\r\n<\/code><\/pre>\n"},{"acf_fc_layout":"content","content":"
    Basemap Gallery and Basemap Toggle components<\/h3>\n
    If your app uses the Basemap Gallery<\/a> or Basemap Toggle<\/a> components (or widgets), validate that they are using the US vector basemaps.<\/p>\n
    Basemap Gallery:<\/strong> If your app uses ArcGIS logins or a global API key, the gallery is configured automatically using your portal settings:<\/p>\n
    (b) Request interceptors. In the esriConfig<\/a> class, set request.interceptors<\/code><\/a> 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.<\/em><\/p>\n"},{"acf_fc_layout":"content","content":"
    Here is a sample app<\/a> showing how you can set the worldview parameter to get the basemap with a particular worldview.<\/p>\n"},{"acf_fc_layout":"image","image":{"ID":2717412,"id":2717412,"title":"Basemap worldviews","filename":"Screenshot-2025-03-05-at-9.40.07\u202fAM.png","filesize":398154,"url":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2025\/03\/Screenshot-2025-03-05-at-9.40.07\u202fAM.png","link":"https:\/\/www.esri.com\/arcgis-blog\/products\/js-api-arcgis\/developers\/how-to-use-a-basemap-with-a-specific-world-view-in-your-web-app\/screenshot-2025-03-05-at-9-40-07-am","alt":"","author":"10062","description":"","caption":"","name":"screenshot-2025-03-05-at-9-40-07-am","status":"inherit","uploaded_to":2716872,"date":"2025-03-05 18:40:48","modified":"2025-03-05 18:40:59","menu_order":0,"mime_type":"image\/png","type":"image","subtype":"png","icon":"https:\/\/www.esri.com\/arcgis-blog\/wp-includes\/images\/media\/default.png","width":1276,"height":599,"sizes":{"thumbnail":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2025\/03\/Screenshot-2025-03-05-at-9.40.07\u202fAM-213x200.png","thumbnail-width":213,"thumbnail-height":200,"medium":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2025\/03\/Screenshot-2025-03-05-at-9.40.07\u202fAM.png","medium-width":464,"medium-height":218,"medium_large":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2025\/03\/Screenshot-2025-03-05-at-9.40.07\u202fAM.png","medium_large-width":768,"medium_large-height":361,"large":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2025\/03\/Screenshot-2025-03-05-at-9.40.07\u202fAM.png","large-width":1276,"large-height":599,"1536x1536":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2025\/03\/Screenshot-2025-03-05-at-9.40.07\u202fAM.png","1536x1536-width":1276,"1536x1536-height":599,"2048x2048":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2025\/03\/Screenshot-2025-03-05-at-9.40.07\u202fAM.png","2048x2048-width":1276,"2048x2048-height":599,"card_image":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2025\/03\/Screenshot-2025-03-05-at-9.40.07\u202fAM-826x388.png","card_image-width":826,"card_image-height":388,"wide_image":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2025\/03\/Screenshot-2025-03-05-at-9.40.07\u202fAM.png","wide_image-width":1276,"wide_image-height":599}},"image_position":"center","orientation":"horizontal","hyperlink":"https:\/\/developers.arcgis.com\/javascript\/latest\/sample-code\/basemap-worldview\/"},{"acf_fc_layout":"content","content":"