Icons can be defined in element styles (both in a workspace, or via a theme), for rendering on elements and groups, as shown in the example below.

Supported formats

The supported image formats are PNG, JPG, and SVG; specified using a URL or a base64 encoded data URI. When referencing images from a URL, if you are using the cloud service or an on-premises installation via HTTPS, the image must be served over HTTPS too.

Potential issues

There are two potential issues that you may encounter when using icons/images:

  1. Images don't render (you may see errors in your web browser's developer console about images being blocked)
  2. Diagrams fail to export to PNG/SVG formats (you may see errors in your web browser's developer console about the canvas being "tainted")

Both of these problems are generally caused by your web browser blocking access to the images due to the restrictions associated with Cross-Origin Resource Sharing (CORS). For this reason, the web server hosting your image must set the Access-Control-Allow-Origin header to allow cross-origin requests. See Allowing cross-origin use of images and canvas for more details.

To avoid these problems, you can alternatively specify your icons as a base64 data URI instead. You can find utilities to convert an image file to a base64 encoded data URI in the Structurizr client libraries, and online.