What is a choropleth map?

A choropleth map shades real geographic regions - countries, states, districts - based on a measure's value, using a color gradient from low to high. It's the chart type for spotting geographic patterns at a glance: which regions are strongest, which are lagging, and how the value is distributed across a real map rather than an abstract chart shape.

How does the chart know which map to show?

Map Region in Map Settings lets you choose explicitly from 10 maps - World, India (States or Districts), USA (States or Counties), UK, Australia, UAE, China, or Europe. If left on World and your dimension field's values match a recognizable set of regions - Indian states or districts, US states, UAE emirates, or major UK cities - the chart automatically switches to that more specific map. This auto-detection only ever overrides World; an explicitly chosen map is never silently swapped out.

Do my region names need to match the map exactly?

No, within reason. The chart normalizes your data's region names against the actual map's feature names before rendering - case differences are ignored, and a shortened name like 'United States' correctly matches the map's full 'United States of America.' A region name that doesn't match closely enough simply won't get shaded - it stays the default area color - rather than causing an error.

Why doesn't a country acronym like USA or UK shade correctly?

Acronyms aren't recognized yet. 'United States' matches the map's 'United States of America' because it's the literal start of that name, but 'USA' and 'US' are too short and too different in spelling for the matching to connect them - they're treated as unmatched and shaded the default area color instead. Use the country's actual name, or a shortened version that's still a literal prefix of it, until acronym support is added.

Why don't region labels show even though I turned them on?

Region labels only render once the map's zoom level is at or above 1.2x. The default zoom is exactly 1.2x, so labels appear immediately at the default view - but if you (or a viewer with Pan/Zoom enabled) zoom out below that threshold, labels disappear automatically until zooming back in. This is intentional, to avoid cluttering a zoomed-out view with overlapping text.

Can viewers pan and zoom the map?

Yes, by default. Enable Pan/Zoom in Map Settings controls this - when on, viewers can drag to pan and scroll to zoom, and region labels show or hide live as the zoom level crosses the 1.2x threshold. Turn it off to lock the map at its initial view.

When should I use a choropleth map instead of a bar chart?

Use a choropleth map when the geographic pattern itself is the insight - which regions cluster together, how a value spreads across neighboring areas. Use a bar chart when precise ranking and comparison matter more than geography, since reading exact values from map shading is much harder than reading bar lengths.

Choropleth Map | Edilitics Docs

Shade a real map by region based on a measure's value, with automatic region matching. Best for geographic comparisons across countries, states, or districts.

A choropleth map shades real geographic regions based on a measure's value, using a color gradient from low to high. Drop exactly one categorical or date field into Column - its values are matched against region names on the map - and exactly one numeric field into Row to drive the shading. Use it when the geographic pattern itself is the insight, not just the ranking.

Loading map…

When to Use

A choropleth map answers "where is this strong, and where is it weak" in a way a bar chart can't - by placing the answer directly onto real geography, so clusters and regional patterns are visible at a glance. Revenue by country, signups by state, support tickets by district - any measure that varies meaningfully by location benefits from being seen on an actual map rather than a list of regions sorted by value.

Map Region is a real, explicit choice - not just an automatic guess. Map Settings lets you pick from 10 maps directly: World, India (States or Districts), USA (States or Counties), UK, Australia, UAE, China, or Europe. Auto-detection only kicks in as a fallback when the map is left on World and your data's region names look like a clear match for one of five specific region sets - it never overrides a map you've explicitly chosen.

Switch to a different chart when:

Precise ranking and comparison matter more than geography - use Horizontal Bar
You need individual point locations, not shaded region boundaries - use Scatter Map
Your region field isn't actually geographic - use a Pie Chart or Donut Chart instead

Scenario	Dimension (Region)	Measure
Revenue performance by country	Country	Revenue
Signup volume by Indian state	State	Signup count
Support ticket density by US county	County	Ticket count
Market penetration by UK city	City	Active customers
Survey sentiment by Australian state	State	Average sentiment score

Required Inputs

Field	Type	Count
Dimension (Region)	Categorical or Date	Exactly 1
Measure (Shading value)	Numeric	Exactly 1

For step-by-step build instructions, see Build Your First Chart.

Formatting Options

The Format tab unlocks after both fields are assigned.

Style

Use the chart title to state what the shading represents, since region colors alone don't carry units or context.

Control	What it does
Show Chart Title	Shows or hides the title.
Enter Chart Title	Title text. Maximum 50 characters.
Font family	Font applied to the title.
Font size	5 to 30.
Bold / Italic	Weight and style.
Alignment	Left, center, or right within the chart container.

Map Settings is where the base map itself is chosen, alongside pan/zoom behavior and region styling.

Control	What it does
Map Region	World, India (States), India (Districts), USA (States), USA (Counties), UK (Districts), Australia (States), UAE (Emirates), China (Provinces), or Europe (Countries). Switches the entire underlying map.
Enable Pan/Zoom	Lets viewers drag to pan and scroll to zoom. On by default.
Initial Zoom	1x to 5x. The map's starting zoom level - also the reference point for the region-label visibility threshold below.
Show Region Labels	Prints each region's name directly on the map. Only actually visible once zoom is at or above 1.2x.
Label Color / Label Font Size	Styling for region labels, shown only when Show Region Labels is on.
Border Width / Border Color	The line separating each region from its neighbors.
Default Area Color	Fill color for regions with no matching data - distinct from the value-based gradient applied to regions that do have data.
Low Value Color / High Value Color	The shading gradient's two ends. This is the same setting as Visual Map's Low/High Value Color below - both controls write to the same gradient.

Region labels won't appear just because Show Region Labels is on - the map's current zoom also has to be at or above 1.2x. The default Initial Zoom is exactly 1.2x, so labels show immediately at the default view, but zooming out below that threshold (if Pan/Zoom is enabled) hides them automatically.

Visual Map is the color legend explaining the shading gradient - the same panel used by Heatmap and Treemap's color-by-value feature.

Control	What it does
Show Visual Map	Shows or hides the legend. The shading still applies either way.
Orientation	Vertical or horizontal placement of the legend.
Vertical / Horizontal Position	Where the legend sits within the chart area.
Interactive Range	When on (default), viewers can drag the legend's handles to narrow the highlighted value range.
Low Value Color / High Value Color	The gradient's two ends - the same setting exposed in Map Settings above.

Interactivity

The tooltip appears on hover over a region, showing its name and value.

Control	What it does
Show Tooltip	Shows or hides the tooltip entirely.
Header / value text styling	Font, size, and color for the lines shown in the tooltip.

Animation controls the map's transition when the chart first renders or the data changes.

Control	What it does
Enable Animation	Turns the transition animation on or off.
Duration	How long the transition takes.
Delay	How long the transition waits before starting.
Easing Function	The transition curve.

Emphasis controls the visual response when hovering a region - a highlight color, a scale-up effect, and a drop shadow. The highlighted color follows your gradient's high end automatically.

Control	What it does
Show Emphasis	Turns hover effects on.
Focus Type	Item, Series, or None.
Enable Scale	Scales the hovered region up slightly.
Scale Size	1.0x to 2.0x.
Shadow Blur / Color / Offset X / Offset Y	Drop shadow styling on the hovered region.
Border Width	Border added around the hovered region.

Enable the Toolbox when viewers need to export the chart or inspect its underlying data.

Control	What it does
Show Toolbox	Shows or hides the toolbox icon bar.
Save as Image	Adds a download icon that saves the chart as a PNG.
Data View	Adds an icon that opens the underlying data table in a separate view.

Best Practices

Pick Map Region explicitly when you know your data's geography. Auto-detection is a convenience for the default World view, not a substitute for choosing correctly - if your data is district-level India data, for example, select India (Districts) directly rather than relying on a 10%-match heuristic to catch it.

Check that your region names actually match the map before assuming the chart is broken. A region that doesn't shade isn't necessarily a bug - it may just not have matched a feature name on the currently selected map closely enough. Try the more specific map variant (Districts instead of States, Counties instead of States) if regions you expect to see shaded are showing as the default area color instead.

Spell out country acronyms rather than relying on them. Names like "USA," "US," and "UK" aren't recognized - use "United States" or "United Kingdom" instead. A shortened name still matches as long as it's the literal start of the full name.

Don't rely on Show Region Labels at a zoomed-out view. Since labels need zoom at or above 1.2x, a heavily zoomed-out map - whether set that way deliberately or reached by panning - will hide labels regardless of the toggle. Keep Initial Zoom at or above 1.2x if labels need to be visible without requiring the viewer to zoom in first.

Use a more specific map for denser data, World for broad comparisons. World is the right choice for country-level data; switching to a country-specific map (India, USA, UK, Australia, China) only makes sense once your dimension field is genuinely sub-national.

Reach for Interactive Range in Visual Map when outliers are flattening the gradient. A single extreme region can compress the rest of the map's shading into a narrow band of similar colors. Dragging the legend's range handles to exclude the outlier redistributes the gradient across the remaining regions' actual spread.

FAQs

Need help? Email support@edilitics.com with your workspace, job ID, and context. We reply within one business day.

Choropleth Map