Support — Tile Grid Map Pro

Published by TCViz · support@tcviz.com · Version 1.1.0.0 · Documentation updated 14 September 2026

Video walkthrough

Setup, formatting options and the Pro custom TopoJSON workflow — watch on YouTube.

Quick start

Add the visual to your report from Microsoft AppSource.
Drag your Latitude column into the Latitude field well — decimal degrees, e.g. 40.4168.
Drag your Longitude column into the Longitude field well — e.g. -3.7038.
Drop a numeric field or measure into Value. This is what colours each tile.
In the Format pane, open Map Settings and pick your Country / Region.

The visual works from raw coordinates. There is no region-name or ISO-code lookup — each latitude/longitude pair is assigned to the grid cell that contains it. Coastal points that fall just off the land mask are snapped to the nearest land cell within 3 cells.

How it works

Every refresh follows the same steps, in this order.

1. Rows → coordinates

Each row needs a numeric Latitude and Longitude in decimal degrees (WGS84).
A row whose latitude or longitude is blank or not a number is skipped and counted as without coordinates.

2. Coordinates → tile

Each bundled map is a raster of land cells laid over a latitude/longitude bounding box. A point goes to the cell that contains it.
If that cell is sea (common for coastal cities), the point moves to the nearest land cell within 3 cells. Canarias and Hawaii use grids split 4×4, so they search 12 of their smaller cells: the same distance on the ground.
A point farther away than that is counted as outside the map.
Rows for other countries are not dropped silently: they count as outside the map. Filter them out (for example with a country slicer) when you only want one country.

3. Row limits

On-screen note	Meaning
Showing the first 500 of N rows.	Free tier: only the first 500 rows Power BI sent are placed on the map.
Power BI sent the first 30,000 rows; further rows are not shown.	Power BI's own limit for this visual (Pro, or Free below 500 rows never reaches it).
N rows not shown: X outside the map, Y without coordinates.	Rows from steps 1 and 2 that could not be placed.

At most two notes are shown at a time, under the map.

4. Aggregation per tile

Auto (from field) reads the aggregation Power BI applies in the field well (Sum, Average, Min, Max or Count), from the field's query or its display name ("Average of …"). A model measure gives no hint, so it is treated as Sum. For ratios and averages written as measures, choose Average in Map Settings.
Sum, Average, Min and Max use only rows that have a value: blanks are ignored, not counted as zero. Count counts all rows in the tile.
The tooltip names the aggregation used and shows Rows: N (M with a value) when some rows are blank. Tooltip fields are aggregated with their own field-well aggregation.
Numbers follow your locale and Decimal Places; values of 1,000 and more are shortened to K, M or B, and percent fields are shown as percentages.

5. Colour

The first matching step decides the tile's colour:

Step	What happens
No value	A tile with rows but no value uses No Data Color. Land cells without any row use it too, or are hidden when Show Empty Cells is off.
High contrast	When Windows high contrast is on, every tile uses the theme foreground colour and the value is shown by opacity (25% for the lowest, 100% for the highest). Colour rules are not used.
Colour rules	Only when Enable Rules (switch in the Conditional Formatting card header) is on. Rule 1, Rule 2 (between From and To, inclusive) and Rule 3 are tested in that order; the first match wins. Empty thresholds are ignored. For a percent field, type thresholds as shown: `25` means 25%. Tiles no rule matches use the scale below.
Sequential	Free: fixed blue palette from the lowest to the highest tile. Pro: Color Min → Color Max.
Quantile (Pro)	Tiles sorted by value and split into 5 classes with the same number of tiles each (fewer classes when there are fewer distinct values), coloured Color Min → Color Max.
Diverging (Pro)	When values cross zero, zero gets Color Mid, negatives run to Color Min and positives to Color Max. When they don't, Color Mid sits halfway between the lowest and highest value.
Categorical (Pro)	With a Category field, each tile takes the category with the most rows (ties by name). The 12 categories with the most rows get the report theme's colours, stable per category across filters; all others share grey "Other". Without a Category field, tiles are coloured by their first Label from a fixed 12-colour palette, and no legend is drawn.

Free users who pick a Pro scale or colours see the Free blue palette.

6. Size Pro

With a measure in Size, each tile's width and height become 30% + 70% × √(tile size ÷ largest tile size) of the full tile, so the area grows roughly in proportion to the size value.
Tiles with a blank or negative size are drawn at the 30% minimum.
Size is not applied to Custom TopoJSON regions.

7. Shape and layout

Tile Shape: Square (Free), Circle or Hexagon (Pro). Hexagons shift every odd row by half a tile so they interlock.
Correct Latitude Distortion (on by default): a degree of longitude is shorter on the ground than a degree of latitude, by the cosine of the latitude. The tile height is set to cell height ÷ (cell width × cos(mid-latitude of the map)) times its width, limited to between 0.4 and 2.5, so countries like Norway are not stretched. Turn it off for square tiles.
The map is centred and scaled to fit the visual; if it is too small, the visual asks you to enlarge it.
Labels (Show Cell Labels): when a tile is at least Label Min Tile Size pixels, it shows the value; when it is between half that size and the full size, it shows the first 4 characters of its Label. A label is only drawn when it fits inside the tile.

8. Legend

Situation	Legend
Sequential / Diverging / high contrast	Gradient bar with the lowest and highest value (and 0 for a diverging scale that crosses zero).
Quantile	One block per class with its starting value.
Colour rules on	One swatch per active rule with its condition ("< 0", "0 – 100", "> 100"), formatted like the field, plus "Other" for tiles no rule matches.
Categorical with Category	One swatch per category (and "Other"), at most 2 rows; names longer than 18 characters are shortened.

Position (Top or Bottom), Font, Text Size (7–24) and Text Color are set in Format → Legend.

9. Interaction

Click a tile to filter the other visuals; the rest dim. Click the same tile again, or click the background, to clear.
Ctrl+click adds or removes tiles. Right-click opens the Power BI context menu.
Keyboard: arrow keys move focus, Enter / Space select, Ctrl+Enter adds to the selection, Esc clears, Shift+F10 or the context-menu key opens the context menu.
Selections from bookmarks and other visuals are shown on the tiles.
Tooltip: region name (TopoJSON), up to 3 labels (+N more), the aggregated value, Size, Category (+N more), row count, cell centre coordinates and your tooltip fields.

10. Custom TopoJSON Pro

Choose Custom TopoJSON (Pro) in Country / Region and drag a file onto the visual. The file is read locally; no network request is made.
From the topology, the object with the most geometries is used. Each Polygon or MultiPolygon geometry is one region (holes respected).
Region names come from the properties name, NAME, NAME_1, name_en, NAME_EN, or the geometry id; otherwise "Region N".
Maximum 5 MB. Coordinates must be longitude/latitude (WGS84); projected files are detected and a note explains it. Files that are not TopoJSON or have no polygons are explained too.
The file is stored in the report (.pbix). Save the report after dropping it.

11. Licensing for Free users

Pro options chosen without a licence are simply not applied (square tiles, blue palette, 500 rows, no Size). Custom TopoJSON shows "Custom TopoJSON regions are not available".
Power BI shows its own licence notice (banner and licence icon) naming the Pro features in use. It never appears in Publish to Web, embedded reports or exports, or when the licence cannot be read.

Field wells

Field well	Required	Max	Description
Latitude	Yes	1	Decimal degrees
Longitude	Yes	1	Decimal degrees
Value	Recommended	1	Numeric value used for colouring
Size Pro	No	1	Second measure that scales each tile's area (colour = Value, size = Size). Shown in the tooltip. Not applied in Custom TopoJSON mode.
Tooltips	No	10	Extra fields shown on hover
Label	No	1	Display name (city, region), shown on tiles and tooltips
Category	No	1	Group used by the Categorical (Pro) colour scale: each tile takes the category with the most rows

Row limits

Power BI sends the visual at most 30,000 rows. The Free tier uses the first 500 rows; Pro uses all rows up to 30,000.

The visual tells you on screen when this applies — "Showing the first 500 of N rows" or "Power BI sent the first 30,000 rows" — and how many rows were not shown because they are outside the map or without coordinates.

Built-in maps

27 square tile grids are included: Spain, Canarias, Portugal, France, Germany, Italy, Sicily, Sardinia, United Kingdom, Netherlands, Belgium, Poland, Sweden, Norway, Switzerland, Austria, United States, Alaska, Hawaii, Canada, Mexico, Brazil, Argentina, Colombia, Australia, India and Japan.

Canarias and Hawaii use finer grids (about 380 and 240 tiles) so the islands read in detail.

Tile shape and latitude correction

Tile Shape — Square (Free), Circle (Pro), Hexagon (Pro). Hexagons use offset rows: odd rows are shifted half a tile.
Correct Latitude Distortion (Free, on by default) — tiles take the real ground proportion of each cell at the map's mid-latitude, so northern countries such as Norway, Sweden and Canada are no longer stretched.

Need a geography that isn't on the list? Pro supports your own TopoJSON boundary file — see below.

Free vs Pro

Feature	Free	Pro
27 built-in maps	✅	✅
Rows used	First 500	Up to 30,000
Aggregation — Auto (from field), Sum, Average, Count, Min, Max	✅	✅
Tile shape	Square	Square, Circle, Hexagon
Correct latitude distortion	✅	✅
Size role — tile area from a second measure	❌	✅
Rule-based colour rules, 3 rules	✅	✅
Tooltips, up to 10 fields	✅	✅
Cell labels, legend (top or bottom), decimal places	✅	✅
Borders, selection ring, no-data colour, show/hide empty cells	✅	✅
High contrast and keyboard navigation	✅	✅
Cross-filter, Ctrl multi-select, context menu	✅	✅
Sequential colour scale	Fixed blue palette	Your colours
Diverging scale — neutral colour at zero when data crosses zero	❌	✅
Categorical scale — colour per Category, theme colours, with legend	❌	✅
Quantile scale — 5 classes with an equal number of cells	❌	✅
Custom scale colours (Color Min / Mid / Max)	❌	✅
Custom TopoJSON regions, saved inside the .pbix	❌	✅

There is no upgrade message or badge inside the visual. When a Free user picks a Pro option, Power BI itself shows its licence notification (a feature-blocked banner and the licence icon) with the purchase path. These notifications never appear where licensing is not supported (Publish to Web, embedded reports, exports) or when the licence cannot be read. The 30-day trial and the payment grace period count as Pro.

Custom TopoJSON Pro

Set Map Settings → Country / Region to Custom TopoJSON (Pro).
Drag a .json or .topojson file directly onto the visual. The drop zone appears automatically.
Rows are assigned to regions by point-in-polygon testing and coloured by the aggregated value. A MultiPolygon region counts as one region, and the tooltip shows the region name.
The file is stored inside the .pbix, so it survives closing and reopening the report. Remember to save after dropping it.

File requirements

A valid TopoJSON topology with Polygon or MultiPolygon geometries.
Coordinates in longitude/latitude (WGS84). Files in projected coordinates are detected and the visual explains that they need to be exported in WGS84.
Maximum 5 MB. Invalid or oversized files are rejected with an explanation.

Files are loaded by drag & drop only. The visual makes no network requests, so there is no option to load a file from a URL.

Where to find boundary files

geoBoundaries.org — administrative divisions worldwide
Natural Earth — country, state and province outlines
Your national statistics office — most publish TopoJSON or GeoJSON

Tip: simplify large files at mapshaper.org to 5–10% before loading. The shape stays the same, the file fits the 5 MB limit and rendering is faster.

Aggregation

The default, Auto (from field), follows the aggregation chosen in the field well (Sum, Average, Min, Max or Count). Model measures default to Sum. The tooltip names the aggregation used. Pick Sum, Average, Count, Min or Max in Map Settings → Value Aggregation to override it. Blank values are ignored, not counted as 0.

Keyboard navigation

Key	Action
Arrow keys	Move focus between tiles
Enter / Space	Select the focused tile
Ctrl+Enter	Add the focused tile to the selection
Esc	Clear the selection
Shift+F10 / context-menu key	Open the context menu

Format pane reference

Section	Options
Map Settings	Country / Region · Tile Shape · Correct Latitude Distortion · Value Aggregation · Show Empty Cells · Show Cell Labels · Label Font Size · Label Min Tile Size · Decimal Places
Color Scale	Scale Type (Sequential · Quantile (Pro) · Diverging (Pro) · Categorical (Pro)) · Color Min / Mid / Max (Pro) · No Data Color
Legend	Show Legend · Position (Bottom / Top) · Font · Text Size · Text Color
Accessibility	Show Cell Borders · Border Color · Border Width · Selected Ring Color · Selected Ring Width
Conditional Formatting	Enable Rules (switch in the card header) · Rule 1 (operator) · Rule 2 (between range) · Rule 3 (operator, default > 100)

The legend uses the same scale as the tiles; with the Quantile scale it shows the 5 classes and their break values. With the colour rules on it shows one swatch per active rule with its condition (e.g. "< 0", "0 – 100", "> 100", thresholds formatted like the field, 25% for percent fields) plus "Other" for tiles no rule matches. With the categorical scale it lists the categories and their colours.

Categorical (Pro) uses the Category field: each tile takes the category with the most rows. The 12 categories covering most rows get the report theme's colours, stable per category across filters; the rest share a grey "Other". The legend lists the categories (up to 2 rows, long names shortened) and the tooltip shows "Category: X (+N more)". Without a Category field, tiles are coloured by their first Label and no legend is drawn.

Quantile (Pro) splits the cells into 5 classes with an equal number of cells each, coloured from Color Min to Color Max, so a single outlier does not wash out the rest of the map.

Conditional Formatting is the visual's own card of three rule-based colour rules (Rule 1 and Rule 3 compare with a value, Rule 2 tests a range). It is not Power BI's field-based fx formatting. Turn it on with the Enable Rules switch in the card header. For a percent field, type thresholds as shown: 25 means 25%.

FAQ

Rows are reported as "outside the map" (or "No rows fall inside …").

Those coordinates are more than 3 cells away from any land cell of the selected map. Check that Country / Region matches your data, that Latitude and Longitude are not swapped, and filter out other countries with a slicer — rows from other countries always count as outside.

All tiles have the same colour, or my colour rules don't apply.

Check the Enable Rules switch in the Conditional Formatting card header. Rules are tested 1 → 2 → 3 and the first match wins, so a wide Rule 2 range can hide Rule 3. For a percent field type 25, not 0.25. With high contrast on, rules are not used. If every tile has the same value, the scale has nothing to spread.

The legend is missing.

Check Show Legend. No legend is drawn when no tile has a value, or with the Categorical scale and no Category field. A very small visual may leave no room.

An average looks like a sum.

A model measure is aggregated as Sum by default. Set Value Aggregation to Average in Map Settings; the tooltip shows which aggregation is used.

Labels are not showing.

Turn on Show Cell Labels. A label is only drawn when it fits: enlarge the visual, reduce Label Font Size or Decimal Places, or lower Label Min Tile Size.

My TopoJSON is not loading.

You need Pro and Custom TopoJSON (Pro) selected before dropping. The file must be a TopoJSON topology (not GeoJSON) with polygons, up to 5 MB, in longitude/latitude. Read the note under the map: it says which of these failed.

What coordinate format does it expect?

Decimal degrees in WGS84 — 40.4168, not 40°25'00"N. Convert DMS values before loading.

Some tiles are empty.

Those grid cells have no matching coordinates. Turn off Show Empty Cells in Map Settings to hide them.

I see "Showing the first 500 of N rows".

Expected on the Free tier, which uses the first 500 rows. Aggregate your data upstream, or use Pro for up to 30,000 rows.

Values don't match my card visual.

Check the aggregation named in the tooltip. With Auto (from field) the visual follows the field-well aggregation; set Value Aggregation explicitly in Map Settings to match the card.

I bought Pro but the features are still locked.

Sign out of Power BI Desktop and sign back in to refresh your licence status. The visual reads the licence after the first render and repaints with all rows once it arrives, so give it a moment.

My dropped TopoJSON disappeared after reopening the report.

It shouldn't — the file is persisted into the .pbix. Make sure you saved the report after dropping the file.

Does the visual send my data anywhere?

No. The visual makes no network requests at all: no telemetry, no analytics, no cookies, and your data never leaves the Power BI environment. See the Privacy Policy.

Report a bug or request a feature

Open an issue on GitHub: github.com/tinocallarisa-web/tile-grid-map-pro/issues
Or email support@tcviz.com. We aim to reply within two business days.

Changelog: CHANGELOG.md