Tooltips

Tooltips are what someone reads when they hover a feature on the map. A good tooltip turns raw data into something a viewer can scan in a second; a bad one dumps every column in the dataset at them and asks them to figure it out.

Tooltip settings live at the project level in the Tooltips tab. That means a single tooltip configuration covers every view, shared link, and embed in the project. Set it once, ship it everywhere.

How tooltips work

A tooltip has three parts: an optional title, a list of fields to show, and a shared appearance. Tooltips only render when there’s something to display. If a feature has no usable title and no enabled fields, Topologis won’t show an empty box.

Title field

The title is the first thing someone reads, so it should answer “what is this?” before anything else.

You can pick Auto or any specific field. Auto is the safe default: it looks for name, then title, then id, and uses the first one that has a value. That covers most data and avoids picking a useless ID when a real name is present.

Pick a specific field when Auto doesn’t get the right one. For example, when your features have a generic name column that’s actually a code, and the human-readable label lives in display_name.

Showing and hiding fields

Below the title is the list of fields that appear in the body of the tooltip. Each one can be enabled or disabled independently.

Most imported data ships with more columns than a viewer needs. Default to disabling everything internal (IDs, system timestamps, foreign keys, raw enum values) and enabling only the fields that help someone understand what they’re looking at.

If a field you’d configured later disappears (because the underlying data changed), Topologis keeps the override and marks it as missing rather than silently removing it. That way you don’t lose your work if a column gets renamed temporarily.

Renaming fields and picking a display type

Each enabled field can have its own label and display type.

Leave the label blank to use the field’s original name. Set a custom label when the original is too technical, too cryptic, or too long for a tooltip: population_2020 becomes “Population”, co2_emissions_tons becomes “CO₂ (tons)“.

For display type, you can leave it on Auto or explicitly pick String, Number, Date, Boolean, or JSON. Auto is fine when the raw values are clean. Reach for an explicit type when the data is messy: for example, when numbers are stored as strings, or when timestamps need to be formatted as dates rather than printed verbatim.

Number formatting

For number fields, you have three formatting styles: Decimal, Currency, and Percent.

Decimal is the everyday choice for raw measurements, counts, and scores. Currency adds a currency symbol, lets you pick the currency code, and respects locale conventions for thousand separators and decimal placement. Percent is most useful when your raw values are already in the 0–1 range and you want them rendered as 0%–100%; the multiplier handles that conversion so you don’t have to preprocess the data.

Each style supports the usual fine-tuning: minimum and maximum fraction digits, grouping, notation (compact for “1.2M” instead of “1,200,000”), and sign display. Use compact notation when tooltips are getting cramped, fixed digits when you need predictable alignment.

Date and time formatting

For date fields, you can override locale, time zone, date style, time style, and 12- vs 24-hour clock.

This matters when the source data uses one convention but the audience expects another. Server logs in UTC, but the viewer is reading the map in Tokyo. Timestamps stored as ISO strings, but the audience reads them in plain English. Set a locale and time zone on the field and the map handles the rest.

Null and empty values

Real data has gaps. Each field can define its own fallback labels for missing or blank values, plus an optional prefix and suffix.

Reach for Null Display and Empty String Display when you’d rather show “Unknown” or ”—” than a literal empty space. Use prefix and suffix to attach short units that don’t belong in the field name: ”$” before a price, “km” after a distance.

Tooltip appearance

The visual side of tooltips is configured once for the whole project: font size and color, padding, background color, border radius, border width, border color, and shadow.

These controls shape the container, not the individual fields, so changes apply uniformly across the map. If you’re tuning the look to match a specific brand or surrounding page, this is where to do it. To bring layer styling into the same conversation, see Styles.