Making Your Pop-up Pop!

The default pop-up theme (left) and the themed pop-up (right)

The default pop-up theme (left) and the themed pop-up (right)

Want to make a beautiful pop-up to match your map or website? With a little elbow grease, CSS, and a keen eye for design, it’s easy. Here’s how you can skin the ArcGIS API for JavaScript pop-up widget.

The pop-up widget provides an attractive user interface for displaying information about a feature or set of features on a map. In this post, I’ll be showing how to improve the default popup style (shown at above left) using my own color scheme and icons (shown at upper right).

Before we get started, you can view the finished pop-up style or grab the code.

You haven’t created it yet, but you need to name your masterpiece theme. The theme name will be assigned as a CSS class. I’ve named my custom theme “modernGrey,” but you can define your own like “blueSteel” or “magnum”. Make sure it doesn’t have any spaces or symbols.

Next, we need to create a style sheet for the new pop-up styles and link it in the head of our HTML document we’ll be embedding that killer webmap in.

<link rel="stylesheet" type="text/css" href="css/modernGrey.css">

Grab the CSS that the pop-up widget uses from the API URL. The CSS from the API is minified to reduce file size. You can make it readable by using a site like cleancss.

Converting minimized CSS into beautiful CSS

Converting minimized CSS into beautiful CSS

Then, you can paste the formatted code into a new empty CSS file. This CSS will let you easily recognize what styles are being applied so you can identify the ones you need to overwrite without having to use a browser’s DOM inspector.

Now we’re ready to start styling with CSS.

In my “modernGrey.css” style-sheet, I can copy all the selectors that I would like to modify without their properties and paste them into my modernGrey.css. I need to add my “modernGrey” class to the selector, so that each of my style-sheet’s selectors overwrites the default ones.

.esriPopup.modernGrey {
// Put styles here!

I can add all the attributes and their properties to the selectors to give my style the look and feel I want.  To easily create multi browser compatible CSS gradients, rounded corners, shadows and text-shadows, is a great resource. can help you create an animated GIF image to match your pop-up.

Styled pop-up

Styled pop-up

.esriPopup.modernGrey {
-webkit-box-shadow: 1px 1px 3px #dbdbdb;
box-shadow: 1px 1px 3px #dbdbdb;
-webkit-border-radius: 2px;
border-radius: 2px;
font-family: Arial, Helvetica, sans-serif;
font-size: 12px;
line-height: 16px;

The pop-up also uses images for icons and each tail of the popup. These images are combined into one image called a sprite. The advantages of having them in a sprite are the reduced file size and once one is loaded, all of the images are already cached in the browser. You’ll likely want to modify the pop-up’s sprite image to match your new theme’s CSS as well.

You may just want to simply change the hue/saturation of the icons with a program like Adobe Photoshop.

Adjusting the color of the arrow icon in the image sprite

Adjusting the color of the arrow icon in the image sprite

You can open the popup.png sprite in your favorite image editor and change what you need or create your own unique sprite.

If you change the size, layout, or position of an image inside of the sprite, you’ll need to adjust the CSS positioning as well.

.esriPopup.modernGrey .titleButton.prev {
background-position: 0 -224px;

Now we need to use JavaScript to tell our map about our cool new theme.

Create your popup Dijit and assign it to a variable. I’ve configured my pop-up with the highlight symbol disabled. Make sure to assign it to a variable that you can access a few lines later.

var customPopup = new esri.dijit.Popup({
fillSymbol: false,
highlight: false,
lineSymbol: false,
markerSymbol: false
}, dojo.create("div"));

Then, we need to apply the theme to the variable’s DOM node (Document Object Model) as a class name, so the styles we create will get applied to this node.

dojo.addClass(customPopup.domNode, "modernGrey");

Lastly, when creating our map, we need to set the map options to use our custom pop-up instead of the default.

var mapDeferred = esri.arcgis.utils.createMap(webmap, "map", {
mapOptions: {
infoWindow: customPopup, // Use our popup
slider: true

Other examples of styled pop-ups include the Public Gallery template in red, blue and green.

Applying a fresh coat of paint to the pop-up goes a long way but don’t forget about the content inside. Refer to the recent Designing web map pop-ups blog post for tips on how to display content within a pop-up.

Happy styling!

Create Popups | Customize Popups

This entry was posted in ArcGIS Online, Developer, Mapping, Web and tagged , , , , , , , , , , , , . Bookmark the permalink.

Leave a Reply


  1. cleung says:


    Great article. Thank you for your post. Esp. like the extra resources ( that you pointed out!

    I want to apply my own style to an infoWindow (not popup), but the code below dosent work. Any idea what else i should do?
    dojo.addClass(infowindow.domNode, “modernGrey”);

    • Matt Driscoll says:

      Hi Connie,
      You can use the same approach for styling the infoWindow. However, the infoWindow uses a large image sprite for nearly all the design. Here’s a code sample you can download to see how. Let me know if that helps!

  2. mhaberk says:

    I’m trying to use the large arrows in the popup.png sprite but when you click the window still acts like the smaller arrows are on the window, how do I get the pop up winow to adjust to recognize the larger arrows are present?


    • Matt Driscoll says:

      Newer versions of the API doesn’t use the large popup tail arrows anymore.

      • says:

        Hi Matt,

        I’ve just got this running too and it looks really good. However, also having a problem with the large (diagonal) arrows: they display but overshoot the graphic being hovered over. Could you expand on how best to solve this? Can you make the popup use a slightly larger offset when displaying with the diagonal arrows? I’m not up to making new arrows myself (I’m a bit challenged in the art department!).

        Thanks for putting this together in the first place.

        • Matt Driscoll says:

          Hey Simon, I don’t think it will be easy to do since the popup calculates where to go. The latest version of the API doesn’t use these long tails which may be easier to work with.

  3. christopher.wesson says:

    Any way to load a custom pop-up into ArcGIS online (in map viewer) instead of into a html page?

  4. stacyculpepper says:


    Just read your blog post above and have a question: How the hell do you use this in ArcMap Desktop!!??? ESRI provides the most spartan documentation on this tool I have witnessed in 18 years. ( I’d like to take my multi-year interval data and make the bar charts as seen in the example. But there is no documentation on how to do that.


  5. dround87 says:

    Hi Matt,

    I’m really trying to make the pop up be the same height as the screen. Any tips? I’m a little stuck on it to be honest.

  6. dround87 says:

    Hi Matt,

    I’m really trying to make the pop up be the same height as the screen. Any tips? I’m a little stuck on it to be honest.