Image Gallery

The Image gallery is a centralized repository for storing and managing images in ThingsBoard. Upload logos, icons, backgrounds, or any visual asset and reuse it across Dashboards, Widgets, device profiles, and mobile applications — ensuring a consistent, branded look across the platform.

Available since ThingsBoard 3.6.2.

The image API uses ETags to optimize caching — images are only downloaded when they have changed, saving bandwidth. By default, no Cache-Control headers are applied. You can customize caching behavior through environment variables:

A longer TTL improves load time for repeated visits and reduces server load; a shorter TTL ensures users see updated images sooner. See the Configuration guide for instructions on changing these values.

Add images in native image file format (PNG, JPEG, GIF, etc.) or as a JSON export.

1. Go to the Resources ⇾ Images.
2. Click the Upload image button in the top-right corner.
3. Select an image or drag it into the upload window, then click Upload.

Go to the Resources ⇾ Images page and click the Upload image button. Drag and drop an image file or click Browse to select it. Optionally, change the image name before uploading. Click Upload. The uploaded image appears in the Resources ⇾ Images list and is ready to use in widgets and dashboards.

1. Click the Import image icon in the top-right corner of the Resources ⇾ Images page.
2. Upload a JSON image file and click Import.

Go to the Resources ⇾ Images page and click the Import image from JSON button. Drag and drop an image JSON file or click Browse to select it, then click Import. The imported image appears in the Resources ⇾ Images list and is ready to use in widgets and dashboards.

The gallery includes built-in system images you can use in dashboards and widgets. By default, only tenant images are shown. Enable the Include system images toggle to see both.

By default, only your images are displayed After enabling "Include system images"

Images can be displayed in list or grid mode. Switch between them using the toggle in the top-left corner of the gallery.

List view Grid view

Download an image in its original file format:

• List view — click the Download image icon next to the image name.
• Grid view — hover over the image and click the Download image icon.

Click the Download image icon in the list view to download the image. Click the Download image icon in the grid view to download the image.

Export an image as a JSON file (useful for migrating images between ThingsBoard instances):

• List view — click the Export image to JSON icon next to the image name.
• Grid view — hover over the image and click the Export image to JSON icon.

Click the Export image to JSON icon in the list view to export the image configuration. Click the Export image to JSON icon in the grid view to export the image configuration.

After adding an image to the gallery, you can embed it in HTML Card widgets, the HTML section of the widget editor, cell content functions, custom actions, and more.

Each image has a unique URL. Use the snippet that matches your context:

Plain HTML (no authentication — use in HTML Card widgets, cell content functions, etc.):

<img src="relative link to the image" alt="text description of the image" />

Angular HTML template (with authentication — use in Markdown/HTML Card widget, widget editor HTML section):

<img [src]="'image URL' | image | async" />

The Angular method automatically includes authentication headers, allowing the same URL to return different images for different users.

To get the embed link:

1. Click the Embed image icon next to the image name (in grid view, hover first).
2. Select the code snippet type (Angular or plain HTML) and copy the unique image URL.

Click the Embed image icon to generate image embed code snippets. Copy the generated code snippet for plain HTML components or Angular HTML templates.

Click the Edit image icon next to the image name (in grid view, hover first) to open the editing window. From here you can rename, download, export, embed, or update the image.

Click the edit icon to open the editing window Editing window with rename, download, export, embed, and update options

To rename an image, enter the new name and click the Save icon.

Enter a new name Name saved successfully

Replacing an image is useful when the same picture serves as the background for multiple dashboards — update it once and all references automatically reflect the new version.

1. Open the image editing window and click Update image.
2. Select a new image or drag it into the window, then click Update.
3. The image is updated. All dashboards and widgets referencing it now show the new version.

Open the image editor and click the Update image button. Select a new image file or drag and drop it into the upload area, then click Update. The selected image is updated successfully and the new preview is displayed.

Delete from list view:

Click the delete icon next to the image name Confirm deletion in the dialog

Delete from grid view:

Hover over the image and click the delete icon Confirm deletion in the dialog

Delete multiple images (list view only):

Select one or multiple images you want to delete, then click the Delete icon in the top-right corner. Click Yes to permanently delete the selected images from the Resources ⇾ Images.