Change images and icons

Many of our themes support images and icons for categories, sections and articles. In many cases images and icons can be changed through theme settings, but some themes require a different approach.

This guide explains how to change default images using theme settings and add new images for themes with more complex layouts and image requirements.

Using theme settings

Because we cannot know how many categories or sections a Help Center will have ahead of time, themes that feature category images or custom blocks allow up to 8 images to be specified through theme settings. If this is more than the number of categories that you wish to display, you can simply change the images using the settings in the Images section when customizing your theme in Zendesk Guide.

Using theme assets

Our Azura theme is an example of a more complex layout which features section images. Because the number of sections within a Help Center is typically much greater than 8, it is necessary to add your custom section images as theme assets.

The process for adding or updating images involves two steps:

  • Add your images

    The first step is to add your images to the theme’s assets/ folder, which you can do directly by copying files into the directory before the theme is imported into Zendesk or through the Zendesk Guide Theming Center.

  • Update your templates

    Once your images have been added you can reference them in your page templates by using the {{asset}} helper.

    It accepts only one parameter: the filename of the asset.

    <img src="{{asset 'background-image.png'}}" alt="Background image">

    The following additional attributes are supported:

    • prefix (optional) adds a prefix to the filename.
    • suffix (optional) adds a suffix to the filename.

    Zendesk’s Curlybars is similar to Handlebars and allows you to reference the current loop index within an {{each}} loop using @index. This allows you to link images to categories or other Help Center properties using their position.

    For example, the following code loops though categories on the Home page and generates the image src attribute using the @index property:

    {{#each categories}}
      <img class="h-8" src="{{asset @index prefix='category-' suffix='.svg'}}" alt="{{name}}">

    Because the index starts at 0, to have the images appear you just need to ensure they adopt the following naming convention in the assets/ folder:

    └── assets/
      └── category-0.svg
      └── category-1.svg
      └── category-2.svg
      └── ...

    For themes like Azura, you’d simply swap categories with sections:

    {{#each sections}}
      <img class="h-8" src="{{asset @index prefix='section-' suffix='.svg'}}" alt="{{name}}">

    You can choose to use other properties with the {{asset}} helper. Using id would allow you to use each category ID as a reference instead.

For more complex use-cases our Images plugin is available.

Questions or feedback about this guide? Let us know