Add Web Images Dynamically to Worksheets

At Tableau, we know that images are a powerful tool when analysing data. Imagine that you're looking at a viz of monthly shoe sales. The data is telling you that you sold more high heels than wedges, but you can't picture the difference in the two types of shoe. That's where Image Role comes in. You can dynamically add web images to your worksheets and use them in your headers to add visual detail.

Viz with images of shoes along with the shoe type and sales

Prepare your data source

Image Role can be assigned to discrete dimension fields that contain URLs that point to web images. To prepare your data, be sure that your image fields meet the requirements set by Tableau to be assigned an image role:

  • Make sure your URLs navigate to .png, .jpeg, .jpg, .svg, .webp, .jfif, .ico, or .gif image files.
  • Verify that each URL begins with http or https. If a transport protocol isn’t included, Tableau assumes https.
  • Optimise the number of images used in your data set. Usually, you can load up to 500 images per field.
  • Ensure that each image file is smaller than 200 kb.

Note: If you're using Tableau 23.1 or earlier, your URLs must navigate to image files with .jpg, .jpeg or .png file extensions.

In Tableau 23.2 and later, .gif files are supported, but .gif animations will only show on Tableau Cloud and Tableau Server with a client-side render. In Tableau Desktop and Tableau Server with a server-side render, the .gif file will show as a static image.

Depending on the complexity of your viz, Tableau may default to a server-side render, which limits the number of images to 100 per field. To learn more about complexity settings and server-side rendering, see Configure Client-Side Rendering.

Example data set:

Product NameProduct Image URLProduct Sales
Flatshttps://img.example.com/flats.png12,118
High Heelshttps://img.example.com/highheels.png15,865
Running Shoeshttps://img.example.com/runningshoes.png14,200
Wedgeshttps://img.example.com/wedges.png8,665

Assign an image role to your URLs

After you’ve connected to your data source, you can assign an Image Role to your URLs from either the Data Source page or on the Data pane in a worksheet.

From the Data Source page:

  1. Locate the column that has image URLs.
  2. Right-click (control-click on Mac) the icon on the top left of the column and select Image Role > URL.
    The icon changes to an image icon, and your images are ready to use.

    Data source option to assign an image role to URLs

From a worksheet:

  1. Open a new worksheet.
  2. Locate a discrete dimension field that has image URLs.
  3. Right-click (control-click on Mac) the dimension field and select Image Role > URL.
    The icon changes to an image icon, and your images are ready to use.

    Data pane option to assign an image role to data

Add images to your visualisations

From your worksheet, drag the Image Role field onto the Rows or Columns shelf. You can now see images along with their associated data on your viz.

Share your visualisations

You can export your workbooks with images and share them. Be sure that the images used in your vizzes are available to be viewed by everyone you share your vizzes with. For example, if you’re using images that are hosted on an internal server behind a firewall, be sure that everyone you share the viz with has sufficient permissions to access the images. In this example, users who view the viz while connected to the same server shouldn’t have any issues seeing the images. But users who export the viz to a PDF on a Tableau Cloud server may not be able to see the images.

If you export your workbook and your viewer attempts to open it in Tableau 2022.3 or earlier, your viewer won’t be able to see the images.

Note: It’s a best practice to always align an Image Role field with a text description to make the content accessible for screen readers and other accessibility software.

Troubleshoot image connections

Sometimes images won't be displayed if you exceed the number of images allowed per field, have large image files on a complex viz or are viewing the viz on a mobile device. This section helps you troubleshoot those errors.

None of the images are being displayed in my viz

There are too many images in the viz
Tableau couldn't access the images

Some of the images aren't displaying in my viz

The image file is too large
You're using an earlier version of Tableau
The image URL must begin with http or https
The image file must be a URL
The image file type isn’t supported
The image file contains bad characters

The images aren't being displayed outside of my worksheet

The images aren't displaying in Viz in Tooltip
The images aren't being displayed in View Thumbnail
The images aren't being displayed when I export my workbook
The images aren't being displayed on a mobile device