Using the image-map appearance in Survey123

09-26-2019 04:05 PM
Esri Contributor
14 30 18.2K

vehicle damageStarting with Survey123 3.6, the field app now supports a new appearance of image-map. This new appearance allows Scalable Vector Graphics (SVG) files to be rendered in your survey form and provides a clickable image for both select_one and select_multiple questions. Choice list selections can now be made by simply selecting different parts of the image. The image-map appearance is currently not supported in the Survey123 web app.

So what is an SVG? An SVG file is an XML-based vector image format for two-dimensional graphics, that has support for interactivity and animation. SVGs also have the ability to have raster image formats such as .png and .jpg embedded within them.

The image-map appearance provides a powerful way to customise the UI of your survey without having to write a single line of code. This enables fast and intuitive data collection with the underlying user selections stored in the feature service. The 'Image-map Sample' survey, available in Survey123 Connect, shows a variety of use cases including Risk Assessment, Body Parts, USA States and Soil Texture.

The animation on the right shows a Vehicle Damage Inspection survey that combines the image-map appearance with the photo watermark feature. This enables the inspection photos to be stamped with the corresponding vehicle part for easy identification later. 

These examples involve relatively complex shapes and highlight what is possible, but the most simple of SVG files can also provide real improvements to survey usability. The ‘big button’ experience is easily set up with a basic SVG file. Also included in the 'Image-map Sample' survey is a ‘Level of Difficulty’ example that is essentially just an SVG file containing 4  clickable <path> elements (plus some text and symbols for ease of use).


Implementing the image-map appearance

The following steps relate to the 'Level of Difficulty' example in the 'Image-map Sample' survey. You can follow this process using the 'difficulty.svg' file attached to this blog.

1) Add a select_one or select_multiple question to your XLSForm (more information on this step).

2) Set up your survey choice list. Each entry needs a list_name, name and label. The values in the name column are the ones that link the choices to parts of your image.


Create an SVG file or assess an existing file for compatibility with Survey123. The second half of this blog goes into more detail on creating SVG images, for now just open 'difficulty.svg' (attached) in a text editor to assess it's compatibility.

  • Ensure that your file has <path> elements with id values that match the name values in your choice list. The <path> elements with id values become the clickable areas of the image.
d="M 5.4998702,5.4998718 H 129.50013 V 194.50013 H 5.4998702 Z"
id="beginner" />

d="M 135.48042,5.4804192 H 259.51959 V 194.51958 H 135.48042 Z"
id="intermediate" />

d="M 265.48041,5.4804192 H 389.51956 V 194.51958 H 265.48041 Z"
id="advanced" />

d="M 395.48041,5.4804192 H 519.51959 V 194.51958 H 395.48041 Z"
id="expert" />
  • Non-clickable areas are <path> elements without id values and other element types eg <rect>, <circle>, <text> etc.
  • See below for more detailed SVG requirements and tips for using with Survey123.

4) Copy your SVG file into the media folder of your survey. The media folder is located in the survey folder  (~\ArcGIS\My Survey Designs\{survey name}) which can be quickly accessed using the Files button in Survey123 Connect. If the media folder does not exist, you need to create it inside the {survey_name} folder.

5) Add image-map to the appearance column, and the name of your SVG file (include the .svg file extension) to the media::image column of your select question.

select_one difficultydifficultyLevel of Difficultyimage-mapdifficulty.svg

That's all there is to it!

Using SVG files in Survey123

While implementing the image-map appearance in Survey123 is simple, the contents of the SVG file itself can get confusing. SVG files can be created in a multitude of ways and each method may introduce issues when trying to use within Survey123. The remainder of this blog post will look at the most common ways of creating an SVG file and the associated tips and tricks for getting them to work in Survey123.

Minimum SVG requirements for Survey123:

  • Must contain a <path> element that has an id value. Non-<path> elements such as <rect>, <ellipse>, <circle>, <image> and <text> will not be clickable. Likewise, <path> elements without an id value will not be clickable.
  • No empty groups. Having empty groups ie <g> </g> within your SVG makes all <path> elements become un-clickable.
  • Can only have 1 group per nest level. You can have as many nested levels as you like, but if you have more than one group at a particular level (including the parent level), all of the <path> elements become un-clickable.
  • SVG height and width (Viewport) must be defined. While your image will likely display properly in Survey123 without these, your clickable areas may become offset from the underlying image.
  • Viewbox must match Viewport (if specified). You don't need to specify a 'viewBox' parameter in your <svg> element. However, if you do specify a viewBox that differs from your height and width values, your clickable areas will be offset from the underlying image.

Other tips for SVG files:

  • Transform functions. It is possible to have SVG elements with transform functions work perfectly in Survey123. However, we must understand that transforms have a cumulative effect when applied to nested elements. It is often best to avoid transform functions if possible.
  • Number of clickable areas. Although most web browsers can render SVG files with up to 5,000 elements without  any issues, these are obviously not practical for use in Survey123. Be mindful that each clickable <path> element needs to be large enough on the screen for the user to select. You'll need to consider what platforms, devices and screen sizes you're using Survey123 on, to decide on a practical limit that suits you.


Downloading the perfect SVG from the web!

So you’ve found the perfect SVG online and have downloaded it for use with Survey123. While the image you found online may look perfect, it needs to include the required <path> elements to be clickable in Survey123.

There are numerous desktop vector graphics programs like Adobe Illustrator, Corel Draw and Inkscape as well as online SVG editors like Vectr, BoxySVG and DrawSVG. Most of these have tools that will convert different types of objects (eg <rect> or <circle>) to <path>, so perhaps your downloaded image can be easily tweaked to suit Survey123.

There are online resources that have SVG files for download that are designed in a way that suits Survey123, particularly those with geography content like and Most SVGs you'll find online have not been designed in this way so open your file in a text editor to quickly assess the contents.

Converting an existing raster image into an SVG

You may have the perfect .png or .jpg raster image that you would like to use with the image-map appearance in Survey123. The image-map appearance only supports SVG files, so you will need to convert your raster to SVG first. Vector graphics programs have tools that basically trace your raster and create SVG objects which can be very effective. Alternatively, online converters such as or can help you achieve this. Results can vary, but some experimentation with the settings and thresholds can yield usable SVGs in no time.

It is best if your raster image contains filled shapes with a limited range of colours. The 'Pipe Fittings' example was created using to first convert a .jpg to SVG. Then the unwanted light grey <path> elements were deleted using a text editor:


Creating an SVG from scratch

lawn varietiesThis option gives you the greatest control over your SVG file. While it is possible to write an SVG entirely in a text editor, vector graphics programs like the ones listed above are the easiest way to create an SVG from scratch. If you're completely new to digital graphics then perhaps the online SVG editors are your best bet. Otherwise, desktop programs often have a larger toolset without limitations on importing and exporting your finished SVG. Inkscape is a free and open source vector graphics editor and was used for some of the SVGs in the sample survey.

The main advantage of using a vector graphics program is that you can easily embed raster images too. Embedding a photo into your SVG can be very useful, for example when the user needs to identify the selection they're making. Here is an example that includes photos of different lawn varieties:


TIP: Having a raster image in the background of your SVG and drawing some simple shapes over areas you would like the user to click is often the quickest and easiest way to create your SVG for use with Survey123. The 'Stranded Oil Distribution' example was created using a .png file as the background image. Then 24 x squares were drawn as <path> elements over the top of the background image. They were given no stroke or fill properties so they are invisible, but they define the clickable areas that correspond to the underlying parts of the background image.

oil distribution

More Information

The image-map appearance type is included in the Survey123 documentation here: Select one and Select multiple.

Detailed information on the SVG specification can be found here: Scalable Vector Graphics (SVG) 1.1 (Second Edition) and Scalable Vector Graphics (SVG) 2

Esri Regular Contributor

Thank you so much for this great explanation! Just thinking of a project where I can implement it. Finally my SVG skills are useful 😄

New Contributor III


I noticed that the image-map appearance doesn't work in Survey123 Web Form. It only displays the image and then the standard select_one or select_multiple question.

Is this functionality in your backlog ?

Overall it's working flawlessly in the field app.


Esri Esteemed Contributor

At this time, image-map is not supported in the web app - Appearance—Survey123 for ArcGIS | Documentation .

Occasional Contributor

This is a great feature - so useful.  Is there any way of altering the dimensions of an image-map question?  If you have a relatively short and wide image/SVG you get a lot of grey space above and below it, which means extra  unnecessary scrolling, plus it looks a bit odd to the user.

Esri Contributor

Hi Colin,

No, this is dependant on both the image dimensions and device type / orientation at the moment. For example the same short and wide image is going to be displayed with the grey space above and below on a phone, but fits nicely on a tablet in landscape.

This could be a good enhancement request to submit via Esri Support if it is important to your survey. Our Support team will assign an official enhancement number and then similar requests from other customers can be attached. This helps us assess demand for the enhancement and prioritize it accordingly.

Best regards,


Esri Contributor

Hi Colin,

I am also excited about svg function and experiencing the same thing.. I just created an ArcGIS Idea based on your and Brett's comments. 

Hopefully the R&D team can implement this function in the near future. 

Allow setting extent for image-map appearance



Occasional Contributor

Thanks both, that's really helpful.  I've voted up your idea Sun and posted a screenshot to illustrate one of the examples we have.

New Contributor III

As a reference for others, only put the name of the SVG in the media::image column, not the path. If you include the entire path, it will work in the preview with Connect, but will not work when published. It took me a while (and several times re-reading) to realize that I don't need the entire path, and that could be why I was having trouble. 

Occasional Contributor II

I am trying to make this work, but I cannot get my selection boxes to be clickable. As far as I can tell, I'm following all the steps properly...having carefully reviewed this post as well as the comments here: Using image-map in Survey123 Connect.  

At first I thought it was the viewport vs. viewbox.  I'm using Illustratror and when I save as an SVG, the XML has a viewBox identified in the code but not a viewport. But, when I added in the width and height, my paths were still not clickable. Then I tried deleting the embedded image code from the XML and voila...I get my clickable boxes! 

So, there's something funky about my image??  It's a placed JPG in the Illustrator file, and I selected the option to embed the image when I saved the SVG. **Note: the image group in the XML is a huge block of gibberishy looking code. Is that normal?  

If you want to have a look, my survey is saved here.

Please help!

Thanks, Lynn

New Contributor II

Hi Brett,

Is there also a max height extent as I have a long thin svg that displays fine if I have it as a note field but as soon as I put it in as a image-map the image displays really small. 

Below are screen shots. First is as a note field, second is as a multi-select image-map using the same svg.

Note Field

Multi-select image-map

Esri Contributor

I noticed that hyperlinks in SVGs are not currently supported yet (from my own testing).

Is there any future plans to support it?

Hyperlinks/Anchors Inside SVG Graphics ← 

Occasional Contributor

Love this Brett!  Finally have some time to dig in and make my own!

Esri Esteemed Contributor

Hi Deon,

I'm not sure I understand the use case for hyperlinks in the image-map context- could you provide an example?

New Contributor

Do you have an example of how the vehicle damage inspection form above is coded? I am trying to put together a similar survey where multiple selections need to be made on one image-map diagram, and a photo needs to be collected for each selection. I have tried using the 'relevant' field, but I must not be inputting things correctly. Any help would be greatly appreciated.

New Contributor II

A style feature that would let us use the extent of the SVG itself or have the ability to assign it a S123 extent would definitely improve the look and feel of some of our surveys that take advantage of the image-map appearance. It seems like in portrait mode a standard size box is generated and the SVG is placed inside of it. Most of our field inspections are completed in portrait orientation, on tablets, and the unused screen space above and below some of our image-maps makes for needless scrolling. These wide SVGs do look as expected in the landscape orientation on a tablet, but this mode doesn't allow as many questions to be visible on screen at once, which causes issues in a form with over 60 questions of varying sizes.

**It really is a nice a feature to have though, looking forward to more improvements!**

Esri Esteemed Contributor

Hi Nya,

I would go about this by having an image question for each possible component a user could select.  Use the selected(${q}, 'choice') function in the relevant column to show the image question if the choice is selected (you cannot use = with multiple choice questions).

Esri Esteemed Contributor

Hi Jason,

What is size/viewbox of the SVG you are using?

New Contributor

Hi James,

Thank you so much! Just tested the question and it worked!

New Contributor II

Hi James,

I have a few SVGs that are doing this in my survey but the one in the picture is the worst of the bunch. 

The size is 475 px X 75 px.

I'm probably going to be reworking these SVGs to have more of a box shape to them.

Thanks for your interest,


Regular Contributor

I've followed the instructions, and this walkthrough but I am still having issues. The SVG displays in my form but the regions aren't clickable. There are no groups and no empty paths, with each path having an ID (A, B and C). What could be causing these problems?

New Contributor

I'm having the same issue and I don't know whay might be wrong.

New Contributor II

You guys would both have to share your SVG's, for us to see whats wrong with them.

Occasional Contributor II

I'm trying to find an svg file for a Risk matrix like the one above that I can edit in a text editor to change some of teh descriptions slightly.  Could anyone point me in the right direction?



Esri Regular Contributor

Do you mean this one?


Occasional Contributor II

Yes, but I need it in the appropriate svg format so that I can change the values/labels in Notepad++ where required

Esri Regular Contributor

Just wanted to make sure...

Would this one work for you?: File:FAA 8040.4B Risk matrix.svg - Wikimedia Commons 

The way the SVG is structured is not really simple (actually you would only need a couple of rectangles and text but this one was probably done in Illustrator...) but if you just want to change the wording you can search in the text editor for the word and then change it, they are <tspan> elements. Changing the color inside the matrix would be a bit more tricky I guess...

Occasional Contributor II

Thanks Nicole...That was kind of what I was after.  I think though a bit of trial and error I should be able to get what I want out of it!

New Contributor

Hi all,  I'm trying to use the image-map feature and I am unable to get the image to even show up in Connect.  I've attempted it with an svg I created, then I downloaded the sample difficulty.svg and followed all the steps.  There is a large empty space where the image should be.  Please help

New Contributor

Thanks for the tips! I downloaded Inkscape and used it to create an svg from an image (embedded in the svg). It works just fine, except the resulting image is too small.

Here is the svg code related to the image size (which is the size of the embedded image):

viewBox="0 0 727 1374"

I would like for it to fit the width of the form. Here is what it looks like on my phone (the Equipment Checklist):

New Contributor II

@JamesTedrick any insight as to whether this functionality will be coming to the webform or not?