Adding labels to ArcGIS Online web maps: Part 1

By Kenneth Field, Esri Research Cartographer

Adding labels to web maps Part 1 thumbnail

Labeling is important for most, if not all, maps so people can interpret and describe patterns they see and to relate them to places. In online web maps, labels are usually only seen as part of the basemap (and un-editable) or as part of the textual information in a pop-up (and un-seen until opened). But how do you add labels to features in Map Viewer so they appear as part of the map? In part one of this two-part blog entry we describe how you can make your own label operational overlays using the Feature Outline Mask tool on annotation feature classes in ArcMap to convert labels to feature geometry. When these are converted to shapefiles they can be added to web maps you make on without having to create and publish map services using ArcGIS Server. Part two of the blog entry will take the approach a stage further by showing you how to add symbols and other graphics to your map as feature geometry.

To demonstrate the technique, we’ll use a world map designed in a similar style to RISK, the board game originally produced in France in 1957 (figure 1). This map provides a good case study because it:

  • is composed entirely of continuous polygons which obscures┬áthe basemap and labels (and which acts as the basemap itself); and
  • contains boundaries that are not coincident with any obvious geography so it requires unique labels.

As figure 1 shows, the pseudo-political geography of the map is hard to describe without labels. You could add them as pop-ups but they require the map reader to have to work harder than necessary to discover basic information that the map should display by default. It could also be argued that the map looks bare or incomplete without labels but since they do not relate to real-world geography it’s unlikely that any published basemap service labels will be useful.

Web map labels Part 1 Figure 1

Figure 1. World map in the style of the RISK board game.

1. Setting the projection in ArcMap

The starting point for creating operational overlay data for your web map will most likely be ArcMap, in which the map in figure1 was created (the connectors you can see are part of the map’s design for the game). Because the operational overlays will be published on you first need to ensure that the map is set up in ArcMap using the Web Mercator Auxiliary Sphere projection. The map projection is set in the Layer Properties (figure 2) and will ensure that subsequent processing steps will create graphics that display correctly when they are eventually added to your web map.

Web map labels Part 1 Figure 2

Figure 2. Web Mercator Auxiliary Sphere selected in ArcMap Data Frame Properties.

2. Adding map labels in ArcMap

In ArcMap data view, you can now label features as you would normally do to alter the font, size and position (read Essential Labeling Concepts for more details on labeling maps in ArcMap). Design your labels so that they function at an appropriate reference scale which fixes the size of text and symbols to draw at the desired height and width at that scale. The labels for the RISK map need to be seen when the map is viewed as a whole so a reference scale of 1:125,000,000 was used (figure 2), they were based on feature attributes, and added to the map using the Label Manager. (read About Displaying Labels for more information).

Web map labels Part 1 Figure 3

Figure 3. RISK map with labels in ArcMap.

3. Converting labels to annotation

Once you have your labels designed appropriately, right click the layer in the Table of Contents and select Convert Labels to Annotation. In the subsequent dialog box, store your annotation in a database and select an appropriate feature class name. The annotation feature class will then be added to your Table of Contents.

Web map labels Part 1 Figure 4

Figure 4. Convert labels to an Annotation Feature Class.

4. Converting annotation to feature geometry

Your labels are now stored as an annotation feature class but for the web map they need to be stored as feature geometry. For this, you use the Feature Outline Masks tool to convert the geometry of the label outlines to polygons in a new polygon feature class. First, locate and run the Feature Outline Masks tool in System Toolboxes > Cartography Tools > Masking Tools (figure 5). Select your annotation feature class as your Input Layer and define an Output Feature Class. The only two parameters that will need changing are the Margin and Mask Kind. Set the Mask to zero and the Mask Kind to EXACT. Ordinarily the tool is used to create mask polygons at a specified distance and shape around features but defining these parameters in this way creates polygons exactly the same shape as the input layer, creating a replica of your labels as polygons. Click OK and once the tool has finished the polygon feature class of your labels will be added to ArcMap.

Web map labels Part 1 Figure 5

Figure 5. Setting parameters using the Feature Outline Masks tool.

5. Converting your polygon feature class to a shapefile

Your new polygon feature class will appear geometrically the same as the input annotation feature class. You have one final step to perform in ArcMap before you can add the labels to your web map because you cannot add data held in a geodatabase to This final step converts your polygon feature class into a shapefile format which can be added to an web map.

Right-click the polygon feature class in your Table of Contents > Data > Export Data and save your shapefile with a suitable filename.

6. Adding your labels shapefile to

You can now add your labels shapefile to your web map using the Add button (figure 6).

Web map labels Part 1 Figure 6

Figure 6. Use the Add button in to add shapefiles.

Figure 7 shows the labels shapefile added to the RISK map in

Web map labels Part 1 Figure 7

Figure 7. Labels shapefile added to the web map

Arranging the labels layer so it is above the other data will position labels on the top of the other content in your web map. As you zoom and pan across the map, the labels behave like any other geographic feature and scale and move accordingly. You can turn the labels on and off in the Contents tab and you can also specify a pop-up to be linked to the label if you wish. Figure 8 shows the finished map which can be viewed as a web map at (best viewed in Chrome or Firefox). Because the labels have been added as an additional operational overlay it overcomes the problem of continuous polygons obscuring basemap detail. The labels allow us to interpret an otherwise unknown geography, having been designed specifically for the map.

Web map labels Part 1 Figure 8

Figure 8. RISK as an web map showing the addition of labels as an operational overlay.

This blog entry has shown you how to migrate labels created in ArcMap into using the Feature Outline Masks tool to create a polygon feature class which is then added to your web map as a shapefile. In part two, we explain how you can create a halo effect for labels in and how you can add other symbols and graphics to your web map.

Thanks to Craig Williams, ArcMap Product Lead, for help in writing the blog entry

This entry was posted in Mapping and tagged , , , . Bookmark the permalink.

Leave a Reply


  1. hunter.greg says:

    Hello – great article? Did “part two” ever happen? I took a look around but couldn’t see anything.


  2. doncatanzaro says:


    I am using ArcMap Desktop Basic (ArcView) and Feature Outline Masks is not available. Are there any alternatives ?

    Thanks !

  3. ranger_nemo says:

    Has there been any updates on labeling in ArcGIS Online? This process works, but only for a small range of scales… Scale out and the labels shrink to nothingness, scale in and they can hide the other features and the basemap. If AGO would share as a MapServer service (as you can with any other Arc Server installation) instead of as a FeatureServer service would allow for the normal labeling system.

  4. slradke says:

    I, too, do not have access to this Feature Outline Mask tool given the level of licensing I have. Any other way to perform this function with only a Standard license? –slr

  5. dlund4 says:

    Awesome! I like to use numerical data as feature labels in ArcGIS Destop. I have been struggling for days trying to find a way to do this with ArcGIS Online. I wish I didn’t have to jump through all the hoops. It seems like it would be a popular feature and that ESRI would make it easier.

  6. mi-glis says:

    Hi, thank you for this information. I’m getting the following message; “Please browse for the target location. The database is currently unknown.”
    Any help would be appreciated.

  7. mcline19 says:

    Is there any new information on labeling features in The methods presented here are not very useful for certain projects.

  8. vickygallardo says:

    We also need a better way to label features in ArcGIS Online. Is this an upcoming enhancement? If so, is there a timeframe?

  9. cartografix13 says:

    The label font looks very odd after uploading; I tried both Calibri and Arial in the original map (created in 10.1) and both converted to something very difficult to read. When I did the same operation using version 10 the labels didn’t look great, but the font was plain enough to read. Thanks. I also would love to see labeling capability in ArcGIS online!

  10. wlynch says:

    Vote to promote the IDEA to add labels to ArcGIS Online Map Viewer– see idea at:
    This is a very nice workaround but it would be nice if it was a bit easier.

  11. says:

    In ArcGIS 10.1, it is necessary to have annotation in a .gdb for the Feature Outline Masks tool to work.
    (In ArcGIS 10, it was acceptable to have annotation in a .mdb .)

  12. maryandrews says:

    Cool, but it didn’t work for my needs. The shapefile for my address labels was too big to work. It did get it to work by creating a feature service and adding the labels that way.
    Thanks. And I agree Labeling is needed upgrade for arcgis online.

  13. maryandrews says:

    Cool, but it didn’t work for my needs. The shapefile for my address labels was too big to work. I did get it to work by creating a feature service and adding the labels that way.
    Thanks. And I agree Labeling is needed upgrade for arcgis online.

  14. cggodfrey0 says:

    I found this VERY useful. I had to fiddle with it a bit for my more updated version of ArcGIS, but IT WORKED. I had a small number of labels (88) so had no problems with size. THANK YOU!

  15. 95vtec says:

    I like the general idea, but it isn’t necessarily useful for a web map that resolves smaller features such as counties and cities. Most web maps have numerous zoom scales and having labels set to a specific a reference scale doesn’t work that well.

  16. waveguide says:

    Wow – we’ve spent (and continue to spend) tens of thousands of dollars on desktop licenses, viewers, server, maintenance agreements etc…a LOT of money, and now still do not have the licensing privledges to access this simple tool that would allow us to simply publish labels as a workaround to a problem (labeling features) that is the most basic of things any user would expect to see when mapping anything. What good is a map if nothing on it can be named or labeled? Amazing sometimes how little these new features seem to be thought out by someone that actually uses maps.

  17. Kenneth Field says:

    While this workflow still works, labels can now be added in ArcGIS Online itself. See

  18. Kenneth Field says:

    Yes, halos and masks need to be switched off

  19. chugach says:

    NOTICE!!! What is not mentioned and is critical to know is you need ArcINFO to do the Mask conversion. THEN you are limited to uploading 1,000 labels to the web map. I hope this saves you half a day as I did 5 layers through the whole process before trying to upload only to find out there is a 1,000 label limit!!!! Please add these limitations to the instructions.

  20. chugach says:

    And it would be nice to add the fact that you need to ZIP the file before uploading to the Web Map.