A heatmap list is a ranked list in which every row is shaded by its value, so the biggest numbers are also the darkest cells. It is the quickest way to turn a table of 10 to 40 items into something a reader can scan in seconds. This tutorial builds one from the latest World Bank figures on air pollution.
What is a heatmap list?
A heatmap list is a list chart that combines a ranked table with a colour scale: each row shows a name, an optional flag or logo, and a value, and the row's background is shaded from light to dark by that value. It answers "who is highest, and by how much?" without axes or gridlines. It is a lighter alternative to a heatmap, which needs two categories, and to a bar chart, which spends space on the bars.
The example: which countries breathe the most polluted air?
Fine particulate matter, PM2.5, is the pollutant most closely tied to health damage, and the World Bank publishes each country's population-weighted annual average as indicator EN.ATM.PM25.MC.M3, based on the State of Global Air estimates. The list below shows the 12 highest countries in 2023, measured in micrograms per cubic metre. For comparison, the World Health Organization's 2021 guideline for the annual average is 5.
| Country | PM2.5, annual mean (µg/m³, 2023) |
|---|---|
| Qatar | 107.8 |
| Saudi Arabia | 73.5 |
| Bangladesh | 69.3 |
| Nigeria | 65.7 |
| Niger | 65.2 |
| Kuwait | 62.3 |
| Pakistan | 58.4 |
| United Arab Emirates | 57.2 |
| Bahrain | 56.6 |
| Cameroon | 55.6 |
| India | 54.1 |
| Nepal | 53.2 |
Qatar is darkest by a wide margin, at more than 21 times the WHO guideline, and even Nepal, in 12th place, is more than 10 times over it. Read the Gulf figures with care: these are national averages that include natural desert dust, not only traffic and industry, so they differ from rankings built on city monitors. For a first look at which chart fits a question like this, see choosing the right chart for your data.
How to create a heatmap list
- Prepare four columns. A name, a value, an image URL and a group: here
country, PM2.5 (µg/m³), flag, region. Sort the rows from highest to lowest, because the list keeps your order. The image and group columns are optional. - Open the Heatmap List template. Start a new project in PlotSet and search the template list for Heatmap List. Sample data is already bound, so you see the layout straight away.
- Insert your data. Upload a CSV (export one from Excel), paste from a spreadsheet, or connect a Google Sheet by its URL. The post 3 easy ways to insert data while charting covers all three.
- Check the bindings. Labels go to the name column, Values to the number, Image URL to the flags and Filter to the group. Always confirm this after an upload, because automatic binding can pick the wrong column.
- Pick the colour scale. The template shades each row between a light and a dark colour. Choose a sequential palette in one hue, and keep text dark enough to read on the lightest row.
- Set the grid. Choose how many columns the list wraps into. The example uses two, so 12 rows fit on screen as a 6-by-2 block. Use one column for a classic vertical list.
- Add a header and a source line. Write a title that states the measure and the year, plus a subtitle for the benchmark. The post make the most of your chart's header explains the options.
- Publish and share. You get an interactive chart, an embed code for any site, and PNG, SVG or JPG export.
When to use a heatmap list
Use it when you want to rank 10 to 40 named items on one measure, when recognisable flags or logos help readers find their own row, or when the story is "who is at the top". The shading adds a second cue to the order, so it works well on slides and in newsletters where a chart is seen for a few seconds. If you need exact values for many rows, a plain table is better.
Avoid it for a long ranking of close values: a shade is harder to judge than a bar length, and the difference between 56.6 and 55.6 is invisible. If readers must compare close numbers, use a sorted bar chart and keep the printed values.
FAQ
What is the difference between a heatmap list and a heatmap?
A heatmap is a grid with two categories, such as weekday against hour, shaded by a value in each cell. A heatmap list has one category, so each row is one item with one value, and the shading repeats the ranking.
Can I add flags or logos to a heatmap list?
Yes. Add a column of image URLs and bind it to Image URL, and each row shows its picture next to the name. Round SVG flags work well.
How many rows can a heatmap list show?
Ten to forty rows read best. Beyond that the list scrolls off the screen, so show the top group and link to the full data.
Where does the PM2.5 data come from?
The World Bank's indicator EN.ATM.PM25.MC.M3, which reports the population-weighted annual mean exposure to PM2.5 in micrograms per cubic metre. The list uses the 2023 values, the latest year available for most countries.
Why is Qatar higher than India in the list?
The World Bank figure is a national average of modelled exposure and includes natural sources such as windblown desert dust. Desert dust can account for a large share of the Gulf figures, which is why they sit above countries where the main sources are traffic, industry and household fuel. The number alone does not say which source is behind it.
Can I embed a heatmap list on my website?
Yes. Publishing gives you an embed snippet that works in any site or CMS, and the list stays interactive. You can also export a PNG, SVG or JPG for slides and print.
