Discover how to build choropleth maps, applying color to geographic features to reveal data patterns and differences across regions.
Choropleth maps depict variances in geographic data by applying color to geographic features based on the values of a specified field, highlighting patterns and differences across regions.
Choropleth maps are widely used in fields like demographics, economics, and public health because they effectively display spatial relationships and trends. By translating numerical data into color categories or gradients, these maps make it easier to interpret complex datasets at a glance, such as population density, income levels, or election results.
After inserting a map, navigate to the Map tab in the right panel. In the Setup section, you can assign basic properties to the map, which are detailed on the Maps overview page. Next, open the Map Type section and click on Choropleth.
In the Basemap section under the Map tab, you can select an underlying basemap for your map element. The basemap is a map, stored in GeoJSON format, consisting of features (geographical shapes) such as countries, provinces, and electoral districts. In order to add a basemap to a map element, you must first add a basemap to your project. This can be done by selecting New Basemap in the Project tab. Clicking Find Basemap then opens a library of more than 600 basemaps to choose from.
If you are on the Pro plan, you can upload your own files (in GeoJSON format) to use as basemaps, by clicking New Basemap, then Upload Basemap.
Next, select a Basemap Join Field. This is a field in your basemap with unique values (e.g. IDs or names) that will be used to link the basemap to the dataset. Values in this field should match values in the Dataset Join Field.
If you're unsure which field to use as the Basemap Join Field, open the selected basemap by navigating to the Project tab and scrolling to Basemaps. Select a feature (geographic shape) on the map, and the Feature tab will display the fields and their corresponding values for the selected feature.
In the Dataset section under the Map tab, you can select the dataset for your map element, which contains the data that you wish to display on the map. In order to add a dataset to a map element, you must first add a dataset to your project. This can be done by selecting New Dataset in the Project tab.
If you are on the Pro plan, you can upload your own files (in csv format) to use as datasets, by clicking New Dataset and then Upload Dataset.
After you have selected a dataset, you can optionally enable the Prefilter Dataset switch, which lets you filter the data that is supplied to the map. The filter is a "prefilter" because it is applied before the visualization is generated; end users are unable to adjust the filter dynamically.
Next, select a Dataset Join Field. This is the dataset field that will be used to link the dataset to the basemap, so it needs to contain values (e.g. IDs or names) that match with values in the Basemap Join Field.
To quickly create a dataset that can be joined to a basemap in your project, go to the Project tab, select New Dataset, then New Dataset from Basemap. You can then pick which basemap fields to store in the new dataset, including the field containing unique values that you will use as your join field.
You can establish connections to filter elements under the Map tab, in the Connections section, by making a selection under Filter.
Filter elements display values from a specified Filter Field, in the form of checkboxes, dropdown menu items, or (for numeric filtering) slider values. A given map can be connected to one or more filters, and the same filter can be connected to multiple maps or other elements. Once connected to a map, a filter element will dynamically control the dataset records passed to the map element, based on user selections made on the filter.
For more details about connecting to filters, see the main Maps page.
In the Colors section under the Map tab, you can assign a Color Field from the selected dataset. Choose either a text or numeric field (e.g., number, currency, percent, or measurement). For text fields, each unique value becomes a category that can be assigned a specific color. For numeric fields, you can configure a Color Gradient, set Domain Minimum and Maximum values, and define the Color Scale. Additionally, you can assign a Missing Data Color and adjust the default Opacity. For more details, see our Colors page.
In the Annotations section under the Map tab, you can add annotations consisting of text and/or symbols to your map.
Begin by picking a longitude and latitude to place the annotation on the map. You can then choose either or both of the following two options:
Tooltips on maps can be enabled by selecting the Map tab, navigating to the Tooltip section, and selecting Display Tooltip. These are automatically configured to display the series fields you have selected in your map.
In situations where the same field has been used more than once (for instance if you are using the same field to set both symbol size and color), the tooltip will only display information about the field once.
You can also optionally set a Color Field Label, which defaults to the name of the Color Field if unset.