Image Roles is a cool, smart and easy to implement feature of Tableau. Put the URL in your dataset, tell Tableau it is a picture, and the picture shows up in the viz.
No local repository, no packaged workbook, and it works in the browser. Here is how to set one up – and the limits you need to be aware of.

Four steps

1. Get your image URLs ready
Every URL has to start with http or https, point at a file smaller than 200 KB, and be reachable without a login. That last one is the rule that breaks most builds – see below.

2. Get the URLs into a field
Either a column in your data, or a calculation. The field must end up as a discrete dimension – Tableau will not offer the Image Role option on anything else.

IF [Status] = "OK"
THEN "https://assets.example.com/icons/check.png"
ELSE "https://assets.example.com/icons/cross.png"
END

3. Assign the Image Role
Right-click the field in the Data pane, then Image Role → URL. Tableau samples a few of the values to check they really are images. If the option is greyed out, the field is not a discrete dimension, or the values do not look like image URLs.

4. Put the field on Rows or Columns
This is the part that surprises people coming from Shapes. An Image Role field is not a mark – it renders as a header. So it goes on the Rows or Columns shelf, not on the Marks card.

The limits listed

Tableau enforces a specific set of constraints. All of them, in one place:

Most important limits

The requirements is quite a list – but most are not a real issue. It depends entirely on how many images you have.

Just a few images – like an on/off toggle, a set of status icons, or a few country flags is no problem. These also hardly exceed 200kb.

Many rows with images – lots of product photos, employee headshots, brand badges – be aware. Keep the number of rows to fewer than 100 (safe for export and mobile views), really max 500. If you use photo’s; compress and scale them down.

Common issues

• No Image Role option available
  You can only change discrete string dimensions to an Image Role
• It works on Desktop, but the published dashboard is empty
  Your laptop can reach the intranet image server – Tableau Cloud/Server cannot. Any internal URL behind a VPN, an SSO login or a signed link will fail once published. Host the images on a public webserver.
• Some images load, others do not
  You are over the per-field cap, or those particular files are over 200 KB. Check the biggest files first.
• Fine in the browser, blank in the PDF or the email
  In exports, thumbnails, Viz in Tooltip and mobile the max is 100 images per view – filter the number of rows.
• A colleague sees nothing at all
  They are on 2022.3 or earlier. Image Roles did not exist yet.
• My SVG will not load
  SVG, WebP, ICO, JFIF and GIF only work from 2023.2. Before that it is JPG and PNG only.
• The GIF does not animate
  Animation only plays on Tableau Cloud and Server with client-side rendering. On Desktop, and on any server-side render, it is a still image.
• The raw URL shows up in the tooltip
  Expected behaviour – can’t unfortunately not be changed.
• One specific image refuses to work
  Check the URL for < > & \ ^ ' or a .. sequence. Tableau rejects those outright. Query strings with an ampersand are the first ones to look at

Hosting the images yourself

Because the URL has to be public and stable, where you put the files matters more than with Shapes.

• Use object storage behind a CDN – S3 plus CloudFront, or the equivalent. Cheap, fast, and it will not disappear when someone tidies up a SharePoint site.
• Use SVG where you can (2023.2+). It stays sharp at any size, and it is usually a fraction of the 200 KB budget. This is the one real advantage Image Roles have over a shape palette, where SVG is not supported at all.
• Keep the URL stable, swap the file behind it. Restyle every dashboard in your organisation by replacing one file – no workbook edits, no republishing. This is the single best reason to pick Image Roles.
• Do not hotlink someone else’s images. They will resize them, move them, or block you, and your dashboard breaks with no warning.
• Set a long cache header. Every viewer’s browser fetches these on every load.

Where to use this

Image Roles are the quickest route to a custom UI control in Tableau: combine one with a parameter action and you have a clickable button that no shape palette can match for maintainability. I use exactly that trick to build a proper on/off switch – see Tableau Toggle Button: 3 Ways to Build an On/Off Switch, which compares it against shapes and a dashboard extension.

Limits verified against Tableau’s Image Role documentation, August 2026.