At Tableau, we know that images are a powerful tool when analyzing 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.


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 image files with .png, .jpeg, or .jpg extensions.
  • Verify that each URL begins with http or https. If a transport protocol isn’t included, Tableau assumes https.
  • Optimize the number of images used in your data set. Usually, you can load up to 500 images per field.
  • Ensure that each image files is smaller than 128 kb.

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

Example data set:

Product Name Product Image URL Product Sales
Flats https://img.example.com/flats.png 12,118
High Heels https://img.example.com/highheels.png 15,865
Running Shoes https://img.example.com/runningshoes.png 14,200
Wedges https://img.example.com/wedges.png 8,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.


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.

Add images to your visualizations

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 visualizations

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 is 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 display 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 displaying in my viz

There are too many images in the viz

Depending on the complexity of your viz, you can typically load 500 images per field. If you have a complex viz, it may default to server-side rendering. With server-side rendering, you can load 30 images per field.

If you get an error message that there are too many images in the viz, filter out images and try again.

Tableau couldn't access the images

If you receive broken image icons instead of your images, first confirm that you have sufficient permissions to view the images (or if, for example, they're behind a firewall). Tableau must be able to access the images, and the images can't require a separate authentication to view them.

If you're sure that you have permission to view the images and they're within the size requirements, check that web images are enabled on your settings page.

In Tableau Desktop:

  1. From your workbook, click Help in the toolbar.
  2. Select Settings and Performance > Set Dashboard Web View Security.
  3. Make sure that Enable Web Page Objects and Web Images is checked.

In Tableau Cloud:

  1. From the home page, click Settings.
  2. Under general, scroll down and locate Web Page Objects and Web Images.
  3. Make sure that Enable Web Page Objects and Web Images is checked.

Some of the images aren't displaying in my viz

The image file is too large

Each image file must be smaller than 128 kb to render. Check your image file size and try again.

The image URL must begin with http or https

Each image URL must begin with either http or https. Tableau doesn't currently support FTP/SMTP calls. Verify your URL format and try again.

The image file must be a URL

An Image Role can be assigned to only URLs that navigate to image files with .png, .jpeg, or .jpg, extensions. Verify your URL format and try again.

The image file extension is not supported

An Image Role can be assigned to only URLs that navigate to image files with .png, .jpeg, or .jpg, extensions. Currently, Images Role doesn't support URLs that navigate to .svg files. Verify your URL format and try again.

The image file contains bad characters

An Image Role can't be assigned to URLs that have the following characters:

< > & \ ^ '

or the following character sequences:

.. \\. \r \n \t

Verify that your URL doesn't contain any of these characters or character sequences and try again.

The images aren't displaying outside of my worksheet

The images aren't displaying in Viz in Tooltip

Viz in Tooltip is processed with server-side rendering, which allows you to load up to 30 images per field. Verify that you have fewer than 30 images per field and try again.

For more about server and client-side rendering, see Configure Client-Side Rendering.

For more about using Viz in Tooltip, see Create Views in Tooltips (Viz in Tooltip).

The images aren't displaying in View in Thumbnail

View Thumbnail is processed with server-side rendering, which allows you to load up to 30 images per field. Verify that you have fewer than 30 images per field and try again.

For more about server and client-side rendering, see Configure Client-Side Rendering.

The images aren't displaying when I export my workbook

All exports and export-related features are processed with server-side rendering, which allows you to load up to 30 images per field. Verify that you have fewer than 30 images per field and try again.

The images aren't displaying on a mobile device

Mobile devices have a lower complexity threshold than computers, so the processing is completed through server-side rendering, which allows you to load up to 30 images per field. Verify that you have fewer than 30 images per field and try again.

You can change the complexity settings on your mobile device. For more info on complexity thresholds, see Configure the complexity threshold for computers and mobile devices.

Thanks for your feedback!