> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Map

> Color-coded map that shades geographic regions by a metric value.

A **map** widget displays data on a geographic map, with each region shaded according to a chosen metric. Denser color = higher metric value. Maps are useful for spotting geographic patterns — which countries drive the most spend, which US states convert the best, which regions to expand into.

## When to use a map

* **Geographic performance patterns** — spend, conversions, or CTR by country or US state.
* **Market expansion research** — highlight regions with untapped opportunity.
* **Executive summaries** — a map communicates geographic distribution faster than a table.

## Configure a map

### Mandatory fields

<Steps>
  <Step title="Pick a data source">
    In the **Data sources** section, select the data source to include. Maps work with any data source that includes a country or US-state breakdown.
  </Step>

  <Step title="Pick a Metric">
    Click **Edit** on the **Metric** field to open the picker panel. Pick up to **20 metrics** to make available in the widget's dropdown, reorder them if needed, and set the active one shown by default. The active metric renders as the region shading — for example, Spend, Conversions, or CTR. Denser color represents a higher metric value. New custom metrics can be created directly from the picker panel without leaving the chart widget.
  </Step>

  <Step title="Set the Group by">
    Click **Edit** on the **Group by** field to open the picker panel. Pick up to **20 breakdowns** to make available in the widget's dropdown, reorder them if needed, and set the active one shown by default. The active breakdown renders as the region shading, limited to **Country** (map view set to **World**, shading countries across a world map) and **State (US Only)** (map view set to **United States of America**, shading US states). The map view is derived automatically from the Group by choice — customers don't set it manually. New custom breakdowns can be created directly from the picker panel without leaving the chart widget.
  </Step>
</Steps>

Widget changes save automatically when the settings panel closes. Persist changes to the dashboard by clicking **Save dashboard**.

### Optional fields

* **Widget filter** — narrow the data feeding the widget. See [Filters](/dashboards/filters-and-dates/filters).
* **Hide metric value** — hide items whose **Ad Spend**, **Impressions**, or **Link Clicks** meet a threshold. Two blocks are available: a preset "Value = 0" checkbox per metric, and a custom threshold block with an operator (default `≤`) and value. Both can be combined.
* **Period** — override the dashboard's date range. See [Date ranges](/dashboards/filters-and-dates/date-ranges).

## Reading the map

* **Color intensity** — proportional to the metric value. Darker regions have higher values; lighter regions have lower values.
* **Hover** on a region to see its exact metric value.
* **Regions with no data** render in a neutral color and don't count toward the color scale.

## Comparison mode

**Maps do not render comparison values.** Even when the Compare toggle is on, the map draws only the primary window.

## Widget styling

Global widget style settings — font, border, background, and color themes — apply to every widget through the [Dashboard style settings](/dashboards/building/dashboard-style-settings#global-widget-settings). On top of those, Map widgets have style options unique to this widget type:

* **Map gradient colors** — the two-stop color ramp used to shade regions from low to high metric values. Configure the **Low** stop and the **High** stop, each with its own HEX color. Defaults are light blue (`#DBF8FE`) → dark blue (`#071F9B`).
* **Color bar** — HEX color for the text rendered on the color-scale legend.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The map is empty ('No data available')">
    Confirm the data source provides the Group by dimension selected (country or US state). Not every data source exposes geography at both levels. See [Data not loading](/troubleshooting/data-not-loading).
  </Accordion>

  <Accordion title="Many regions are the same color">
    The metric may have very low variance across regions — most regions cluster near the same value. Try a metric with more spread, or switch the Group by to a coarser view.
  </Accordion>

  <Accordion title="Some regions are missing entirely">
    The data source doesn't have data for those regions in the selected date range, so they render in the neutral no-data color. Widen the date range or check the data source's coverage.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Ads Table" href="/widgets/widget-library/table-widgets/ads-table">
    Row-by-row breakdown with the same metrics.
  </Card>

  <Card title="Column chart" href="/widgets/widget-library/chart-widgets/column-chart">
    Ranked comparison across regions.
  </Card>
</CardGroup>