Insert images and icons into any page in ways that are not possible out-of-the-box.

In this article

Images used in Zendesk themes are stored as theme assets and can be added to a page using the built-in Zendesk {{asset}} helper. Although this approach can be used in a majority of cases, the Images plugin offers several advantages over the helper:

  • Image references can be composed of two or more variables, whereas the image helper only allows for one.
  • Image references can contain a wildcard value (*).
  • You can specify a default image to use in the case where an image is not available.

A very common use-case for this plugin is to display images or icons alongside dynamically-generated category, section or article lists.

We’ve created a guide that explains how to add category, section and article images to a page template in Zendesk Guide.


The following steps describe how to set up and use the Images plugin:

  1. Register assets

    The Images plugin requires that assets that need to be inserted into the page are registered within a window.assets JavaScript variable. This can be done in the document_head.hbs template using a <script> tag and the {{asset}} helper:

     <script type="text/javascript">
       window.assets = {
         "category-1": "{{asset 'getting-started.svg'}}",
         "category-2": "{{asset 'usage-guides.svg'}}",
  2. Update templates

    Elements to be replaced with an image should be updated with the following data attributes:

    • data-asset="image"
    • data-asset-id="{id}" identifying the asset to use.
    • data-default-asset-id="{id}" identifying the asset to use if the asset above has not been registered (optional).

    The ID specified for both the asset and the default (fallback) asset is the object key specified in the window.assets global variable. The ID can identify an asset by name (e.g., “category-1”) or include a wildcard character (e.g., “category-*”):

     <div class="container">
       {{#each categories}}
           <a class="link-plain text-inherit" href="">
         <div class="h-6 w-6" data-asset="image" data-asset-id="category-*"></div>

    Because data attributes are used, you will need to ensure that the allow unsafe HTML setting is enabled within Guide.

    If a wildcard character is used, the plugin replaces the character with an integer representing the current number of assets with the same prefix, starting at 1.

When adding SVG images into a page you can use the data-inline-svg attribute to replace the resulting <img> element with an inline SVG. This allows you to alter the appearance of the image directly using utilities or custom CSS. Read about replacing images with inline SVGs in our documentation for more information.


Name Type Default Description
data-asset-id string
null The ID of the registered asset.
data-default-asset-id string
null The ID of the registered asset to use as a fallback.


There are no custom events emitted by this plugin.