{"id":1040781,"date":"2020-10-22T10:30:00","date_gmt":"2020-10-22T17:30:00","guid":{"rendered":"https:\/\/www.esri.com\/arcgis-blog\/?post_type=blog&p=1040781"},"modified":"2020-10-22T10:32:47","modified_gmt":"2020-10-22T17:32:47","slug":"popups-for-web-developers","status":"publish","type":"blog","link":"https:\/\/www.esri.com\/arcgis-blog\/products\/js-api-arcgis\/developers\/popups-for-web-developers","title":{"rendered":"Pop-ups for Web Developers"},"author":4271,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"open","ping_status":"closed","template":"","format":"standard","meta":{"_acf_changed":false,"_searchwp_excluded":""},"categories":[738191,22941],"tags":[96582,38851,28061,212872,23221],"industry":[],"product":[36831],"class_list":["post-1040781","blog","type-blog","status-publish","format-standard","hentry","category-developers","category-mapping","tag-arcgis-api-for-javascript","tag-developers","tag-pop-ups","tag-popups","tag-web-mapping","product-js-api-arcgis"],"acf":{"short_description":"Learn about some of the subtle yet powerful capabilities of the pop-up that you can take advantage of as a developer.","flexible_content":[{"acf_fc_layout":"content","content":"

Pop-ups are often the single most important aspect of web mapping applications when it comes to enabling interactivity with the map. In fact, a well-designed pop-up can be the difference between a good app and a great app. This article covers some of the subtle yet powerful capabilities of the pop-up that you can take advantage of as a developer.<\/p>\n

Pop-up anatomy<\/h2>\n

A very low-effort way to define the pop-up content \u2013 and how it is displayed \u2013 is by using the ArcGIS Online and ArcGIS Enterprise authoring tools to define the pop-up content for each layer. Then, when you load the layers in your map they \u201cjust work\u201d. Under the hood, the ArcGIS API for JavaScript creates a Pop-upTemplate for each layer. This contains the pop-up elements that have been configured such as the attribute display, media elements like charts, images, etc that you\u2019ve configured, as well as any attachments associated with each feature.<\/p>\n"},{"acf_fc_layout":"image","image":{"ID":1040791,"id":1040791,"title":"popup-anatomy3","filename":"popup-anatomy3.png","filesize":209326,"url":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/popup-anatomy3.png","link":"https:\/\/www.esri.com\/arcgis-blog\/products\/js-api-arcgis\/developers\/popups-for-web-developers\/popup-anatomy3","alt":"","author":"4271","description":"","caption":"The anatomy of a pop-up.","name":"popup-anatomy3","status":"inherit","uploaded_to":1040781,"date":"2020-10-19 22:07:45","modified":"2020-10-22 17:29:24","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":1673,"height":1125,"sizes":{"thumbnail":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/popup-anatomy3-213x200.png","thumbnail-width":213,"thumbnail-height":200,"medium":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/popup-anatomy3.png","medium-width":388,"medium-height":261,"medium_large":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/popup-anatomy3.png","medium_large-width":768,"medium_large-height":516,"large":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/popup-anatomy3.png","large-width":1606,"large-height":1080,"1536x1536":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/popup-anatomy3-1536x1033.png","1536x1536-width":1536,"1536x1536-height":1033,"2048x2048":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/popup-anatomy3.png","2048x2048-width":1673,"2048x2048-height":1125,"card_image":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/popup-anatomy3-692x465.png","card_image-width":692,"card_image-height":465,"wide_image":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/popup-anatomy3-1606x1080.png","wide_image-width":1606,"wide_image-height":1080}},"image_position":"center","orientation":"horizontal","hyperlink":""},{"acf_fc_layout":"content","content":"

Alternatively, developers can programmatically define their pop-up using the JavaScript API’s Pop-upTemplate<\/a> class. It is a little more work, but you can achieve the same look and feel as if it was defined in Online or Enterprise and you gain the ability to do more customization. If you search the ArcGIS blog site, you\u2019ll see a large collection of helpful blogs covering tips, tricks and best practices for designing pop-ups.<\/p>\n

This takes care of the \u201cmeat\u201d of the pop-up, and at this point many developers would consider their pop-up job done. However, you have more options when it comes to tailoring the pop-up experience, and even its content.<\/p>\n

Put anything you want inside a pop-up<\/h2>\n

Version 4.16 of the JavaScript API introduced a new content type to the Pop-upTemplate called \u201cCustomContent<\/a>.\u201d This type of content element can be added to the pop-up just like the other types (attribute tables, charts, etc) and can work with content such as strings, HTMLElements, and API widgets. This gives you a lot of flexibility in terms of what you can easily place inside of a pop-up.<\/p>\n

In the example below, the API’s search widget is embedded in the pop-up as a custom content element.<\/p>\n"},{"acf_fc_layout":"image","image":{"ID":1040801,"id":1040801,"title":"popup","filename":"popup.png","filesize":105171,"url":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/popup.png","link":"https:\/\/www.esri.com\/arcgis-blog\/products\/js-api-arcgis\/developers\/popups-for-web-developers\/popup-26","alt":"","author":"4271","description":"","caption":"In this example, the API\u2019s search widget is embedded in the pop-up as customContent.","name":"popup-26","status":"inherit","uploaded_to":1040781,"date":"2020-10-19 22:10:10","modified":"2020-10-22 17:29:18","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":960,"height":397,"sizes":{"thumbnail":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/popup-213x200.png","thumbnail-width":213,"thumbnail-height":200,"medium":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/popup.png","medium-width":464,"medium-height":192,"medium_large":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/popup.png","medium_large-width":768,"medium_large-height":318,"large":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/popup.png","large-width":960,"large-height":397,"1536x1536":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/popup.png","1536x1536-width":960,"1536x1536-height":397,"2048x2048":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/popup.png","2048x2048-width":960,"2048x2048-height":397,"card_image":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/popup-826x342.png","card_image-width":826,"card_image-height":342,"wide_image":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/popup.png","wide_image-width":960,"wide_image-height":397}},"image_position":"center","orientation":"horizontal","hyperlink":"https:\/\/developers.arcgis.com\/javascript\/latest\/sample-code\/popup-customcontent\/index.html"},{"acf_fc_layout":"content","content":"

At a high level, you\u2019ll follow these steps:<\/p>\n

\/\/ 1. create the custom content <\/span>\r\nlet<\/span> customContent = new<\/span> CustomContent({\r\n  creator: (function<\/span> (graphic)) {\r\n  \/\/ this returns either string, HTMLElement, Widget, or Promise<\/span>\r\n  }\r\n});\r\n\r\n\/\/ 2. Create the PopupTemplate and reference the content elements<\/span>\r\nconst<\/span> popupTemplate = new<\/span> PopupTemplate({\r\n  outFields: [\"*\"<\/span>],\r\n  title: \"State: {state_name}\"<\/span>,\r\n  content: [customContent, chart, textDescription]\r\n});\r\n\r\n\/\/3. Configure the layer to use the popupTemplate<\/span>\r\nlayer.popupTemplate = popupTemplate;\r\n<\/code><\/pre>\n"},{"acf_fc_layout":"content","content":"
One important aspect to note about the code above is the outFields property. For optimum performance, the API only requests the feature attributes that it needs for visualization and those needed for the layer\u2019s pop-up definition (if it was pre-configured in Online or Enterprise). If you are doing something custom, you must specify the attributes that you\u2019ll be working with so that they are also downloaded. In addition to these steps, you can use the customContent\u2019s destroyer property for cleaning up any custom content when it is no longer needed.<\/p>\n
Alternatives to using the default pop-up<\/h2>\n
You might want to display information about a feature in a way that differs from the default pop-up experience. There are a few very helpful mechanisms in the API for building out your own experience. Here are some examples:<\/p>\n
Formatted content outside the pop-up<\/strong>. <\/em>As mentioned earlier, the PopupTemplate is used to display nicely formatted pop-up content. If you\u2019d like to display the formatted content somewhere in your application outside the pop-up, you can use the Feature widget<\/a>. The Feature widget renders information about a feature according to its PopupTemplate. In fact, under the hood, the pop-up uses the Feature widget internally to display content, and surrounds it with the pop-up UI such as the docking control and pagination. The Feature widget can be placed in any container, on top of the map or completely outside the map. Two common examples of this are when you want to display the feature\u2019s information in a side panel next to the map, or if you want to display it in a floating window as you hover over features. In the example below, the Feature widget is displayed inside a side panel.<\/p>\n"},{"acf_fc_layout":"image","image":{"ID":1040841,"id":1040841,"title":"feature-widget-sidepanel","filename":"feature-widget-sidepanel.png","filesize":137013,"url":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/feature-widget-sidepanel.png","link":"https:\/\/www.esri.com\/arcgis-blog\/products\/js-api-arcgis\/developers\/popups-for-web-developers\/feature-widget-sidepanel","alt":"","author":"4271","description":"","caption":"Use the Feature widget to place formatted pop-up content in a side panel.","name":"feature-widget-sidepanel","status":"inherit","uploaded_to":1040781,"date":"2020-10-19 22:28:45","modified":"2020-10-22 17:29:11","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":1285,"height":816,"sizes":{"thumbnail":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/feature-widget-sidepanel-213x200.png","thumbnail-width":213,"thumbnail-height":200,"medium":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/feature-widget-sidepanel.png","medium-width":411,"medium-height":261,"medium_large":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/feature-widget-sidepanel.png","medium_large-width":768,"medium_large-height":488,"large":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/feature-widget-sidepanel.png","large-width":1285,"large-height":816,"1536x1536":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/feature-widget-sidepanel.png","1536x1536-width":1285,"1536x1536-height":816,"2048x2048":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/feature-widget-sidepanel.png","2048x2048-width":1285,"2048x2048-height":816,"card_image":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/feature-widget-sidepanel-732x465.png","card_image-width":732,"card_image-height":465,"wide_image":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/feature-widget-sidepanel.png","wide_image-width":1285,"wide_image-height":816}},"image_position":"center","orientation":"horizontal","hyperlink":"https:\/\/developers.arcgis.com\/javascript\/latest\/sample-code\/widgets-feature-sidepanel\/index.html"},{"acf_fc_layout":"content","content":"
Display more than one pop-up at once<\/strong>. <\/em>In most cases, the best user experience is to show one pop-up at a time, which is how the API is designed. However, some developers have a requirement to display more than one pop-up at once. This can be achieved using multiple instances of the Feature widget, and a pop-up helper method. Rather than showing the information inside a pop-up which automatically closes when another feature is clicked, it is shown in Feature widgets that are added to the UI. You can display them next to the selected feature and provide a button for the user to explicitly close them.<\/p>\n
You will have to do a little plumbing to get this to work. This includes setting the Pop-up\u2019s autoOpenEnabled<\/a> property to false, adding a click listener on the view, and then getting all the features that were clicked on. You can get the features at a given screen location using the PopupViewModel\u2019s fetchFeatures<\/a> method (the business logic that powers the pop-up is the PopupViewModel). You might wonder why you wouldn\u2019t just use the map view\u2019s hitTest for this\u2026 There are two important distinctions with using fetchFeatures: 1) you get all the features in all layers from the client and server rather than limiting it to what is already loaded on the client, and 2) you get the features which have a pop-up enabled and popupTemplate defined for you to use.<\/p>\n
Display pop-up information in a side panel<\/em>.<\/strong> In the following app, multiple Feature widgets are used to display information from three layers at once. Rather than the pop-up information being inside a window near the feature, it is added to a side panel.<\/p>\n"},{"acf_fc_layout":"image","image":{"ID":1040861,"id":1040861,"title":"multiple-layer-popups","filename":"multiple-layer-popups.png","filesize":210209,"url":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/multiple-layer-popups.png","link":"https:\/\/www.esri.com\/arcgis-blog\/products\/js-api-arcgis\/developers\/popups-for-web-developers\/multiple-layer-popups","alt":"","author":"4271","description":"","caption":"Show feature information from 3 layers at once using the Feature widget.","name":"multiple-layer-popups","status":"inherit","uploaded_to":1040781,"date":"2020-10-19 22:29:39","modified":"2020-10-19 22:29:44","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":1500,"height":813,"sizes":{"thumbnail":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/multiple-layer-popups-213x200.png","thumbnail-width":213,"thumbnail-height":200,"medium":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/multiple-layer-popups.png","medium-width":464,"medium-height":251,"medium_large":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/multiple-layer-popups.png","medium_large-width":768,"medium_large-height":416,"large":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/multiple-layer-popups.png","large-width":1500,"large-height":813,"1536x1536":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/multiple-layer-popups.png","1536x1536-width":1500,"1536x1536-height":813,"2048x2048":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/multiple-layer-popups.png","2048x2048-width":1500,"2048x2048-height":813,"card_image":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/multiple-layer-popups-826x448.png","card_image-width":826,"card_image-height":448,"wide_image":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/multiple-layer-popups.png","wide_image-width":1500,"wide_image-height":813}},"image_position":"center","orientation":"horizontal","hyperlink":"https:\/\/developers.arcgis.com\/javascript\/latest\/sample-code\/widgets-feature-multiplelayers\/index.html"},{"acf_fc_layout":"content","content":"
Disable the pop-up altogether<\/strong>. <\/em>If you don\u2019t want to show pop-up information at all, you can disable the pop-up by setting a layer\u2019s popupEnabled to false, or disable pop-ups for all layers like this:<\/p>\n
view.map.layers.forEach( layer => layer.popupEnabled = false<\/span> );\r\n<\/code><\/pre>\n
Fine tuning the experience<\/h2>\n
There are several configuration options related to the pop-up experience that you can try out. A few that are easily overlooked are:<\/p>\n
Customize the feature highlight color<\/strong>.<\/em> When the user clicks on features, what color would you like used for highlighting? You can customize the color by setting the map or scene view\u2019s\u00a0highlightOptions<\/a>.<\/p>\n
Remove parts of the pop-up<\/strong>.<\/em> Using the \u201cvisibleElements<\/a>\u201d property, you can turn individual elements of the widget’s display on\/off including the \u201cclose\u201d button and the navigation controls for cycling through selected features.<\/p>\n
Control docking behavior<\/strong>.<\/em> When a pop-up is “dockEnabled<\/a>” it means the pop-up no longer points to the selected feature or the location assigned to it. Rather it is placed in one of the corners of the view or to the top or bottom of it. Docking the pop-up allows for a better user experience, particularly when opening pop-ups in apps on mobile devices. You can control various aspects of the docking behavior, including the dimensions of the view at which to dock the pop-up automatically (i.e. what screen size should cause the pop-up to be docked for usability?) setting the \u201cbreakpoint<\/a>\u201d property. You can also turn off docking completely if you don\u2019t want your pop-up to switch to docked when the view is small.<\/p>\n
Pop-up styling<\/h2>\n
You can style your pop-up to match the rest of your app and company branding, or change specific elements based on your preferred design. Although it isn\u2019t immediately obvious, the pop-up is a widget, architected in the same way that other widgets are architected in the API. It can be styled in the same way that other widgets are styled in the API<\/a>.<\/p>\n
Use an API theme<\/em><\/strong>: One way to quickly change the style of all widgets in your app at once is to apply a theme<\/a>. You can pick from light (default), dark, light\/dark blue, light\/dark green, light\/dark purple, and light\/dark red (see the dark theme in the app below). A more involved option is to create your own theme and apply it across all widgets. To learn more about doing this, check out the Styling<\/a> topic in the JavaScript API Guide.<\/p>\n
Override individual properties in CSS<\/strong>: <\/em>You can change a handful of properties by overriding the pop-up\u2019s CSS. An easy way to figure out what properties you want to change is to use the browser\u2019s developer tools to inspect and experiment with the CSS of an individual element<\/p>\n
Widget SASS<\/strong>:<\/em> If you need a scalable approach with more fine-grained control, you may want to consider working with the pop-up\u2019s Sass file<\/a>. This is the recommended approach to customizing the CSS as it provides access to theme variables and specificity.<\/p>\n"},{"acf_fc_layout":"image","image":{"ID":1040871,"id":1040871,"title":"dark-theme","filename":"dark-theme.png","filesize":86894,"url":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/dark-theme.png","link":"https:\/\/www.esri.com\/arcgis-blog\/products\/js-api-arcgis\/developers\/popups-for-web-developers\/dark-theme","alt":"","author":"4271","description":"","caption":"Applying a theme changes the color of all API widgets in the app, including the pop-up. In this app, the \u201cdark\u201d theme was used.","name":"dark-theme","status":"inherit","uploaded_to":1040781,"date":"2020-10-19 22:32:05","modified":"2020-10-22 17:29:38","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":1111,"height":711,"sizes":{"thumbnail":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/dark-theme-213x200.png","thumbnail-width":213,"thumbnail-height":200,"medium":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/dark-theme.png","medium-width":408,"medium-height":261,"medium_large":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/dark-theme.png","medium_large-width":768,"medium_large-height":491,"large":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/dark-theme.png","large-width":1111,"large-height":711,"1536x1536":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/dark-theme.png","1536x1536-width":1111,"1536x1536-height":711,"2048x2048":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/dark-theme.png","2048x2048-width":1111,"2048x2048-height":711,"card_image":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/dark-theme-727x465.png","card_image-width":727,"card_image-height":465,"wide_image":"https:\/\/www.esri.com\/arcgis-blog\/app\/uploads\/2020\/10\/dark-theme.png","wide_image-width":1111,"wide_image-height":711}},"image_position":"center","orientation":"horizontal","hyperlink":""},{"acf_fc_layout":"content","content":"
How to learn more<\/h2>\n
We have shared a wide variety of content for helping developers create beautiful, effective pop-ups. Here are some of the resources you can check out if you want to continue your pop-up learning.<\/p>\n
Click on a button, execute a function<\/h2>\n
You can easily configure the pop-up to have one or more buttons that executes a function that you\u2019ve created. These are called pop-up \u201cactions<\/a>.\u201d You may have noticed the zoom-in button that is symbolized by a magnifying class in the default pop-up \u2013 that is an action. When clicked, the map zooms in and centers on the selected feature. You can add any number of custom actions to the pop-up, and control how many are displayed before added to a \u201c\u2026\u201d menu. This capability is most often used when you want the user to be able to do something with the selected feature. For example, if you had a layer containing possible retail locations, you could have an action that when clicked on, it calculates a 10-minute drive-time around the selected feature and displays demographic statistics about people living within the drive-time polygon. Or it could do an intersection using the buffer and another layer in the map. You can decide exactly what you want to happen when the user clicks on your custom action \u2013 the concept of actions was created to give developers an easy way to integrate their custom workflows into pop-ups.<\/p>\n