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

# Area Layer

> Add a choropleth layer to a map

```liquid theme={null}
{% map %}
    {% area_layer
        geography="us_states"
        match_by="name"
        data="state_sales"
        area_id="state"
        value="sum(sales)"
    /%}
{% /map %}
```

## Examples

### US States by Name

```liquid theme={null}
{% map %}
    {% area_layer
        geography="us_states"
        match_by="name"
        data="state_sales"
        area_id="state"
        value="sum(sales)"
    /%}
{% /map %}
```

### US States by Abbreviation

```liquid theme={null}
{% map %}
    {% area_layer
        geography="us_states"
        match_by="abbr"
        data="state_sales"
        area_id="state_abbr"
        value="sum(sales)"
    /%}
{% /map %}
```

### US Counties by State + County

```liquid theme={null}
{% map %}
    {% area_layer
        geography="us_counties"
        match_by="state-county"
        data="county_sales"
        area_id="state || '-' || county"
        value="sum(sales)"
    /%}
{% /map %}
```

### US Counties by FIPS

```liquid theme={null}
{% map %}
    {% area_layer
        geography="us_counties"
        match_by="fips"
        data="county_sales"
        area_id="state_fips || county_fips"
        value="sum(sales)"
    /%}
{% /map %}
```

### Custom GeoJSON

```liquid theme={null}
{% area_layer
    geojson_url="https://example.com/custom.geojson"
    geojson_id="id"
    data="my_data"
    area_id="region_id"
    value="sum(sales)"
/%}
```

### Diverging Scale Centered at 0

```liquid theme={null}
{% map %}
    {% area_layer
        geography="us_states"
        match_by="abbr"
        data="state_growth"
        area_id="state_abbr"
        value="growth_pct"
        color_scale=["#d73027", "#ffffbf", "#1a9850"]
        min=-100
        max=100
        midpoint=0
    /%}
{% /map %}
```

### Custom Breakpoints

```liquid theme={null}
{% map %}
    {% area_layer
        geography="us_states"
        match_by="abbr"
        data="state_sales"
        area_id="state_abbr"
        value="sum(sales)"
        color_stops=[
            { value=0 color="#ffffff" },
            { value=10000 color="#f59e0b" },
            { value=50000 color="#1a9850" }
        ]
    /%}
{% /map %}
```

## Attributes

<ResponseField name="data" type="string" required>
  Name of the table to query
</ResponseField>

<ResponseField name="filters" type="array">
  Array of filter IDs to apply
</ResponseField>

<ResponseField name="geography" type="string">
  Pre-provided geography (use this OR geojson\_url + geojson\_id)

  **Allowed values:**

  * `us_states`
  * `us_counties`
</ResponseField>

<ResponseField name="match_by" type="string">
  How to match areas. For us\_states: "name", "abbr", or "fips". For us\_counties: "state-county" or "fips".
</ResponseField>

<ResponseField name="geojson_url" type="string">
  URL to custom GeoJSON file (use with geojson\_id for custom maps)
</ResponseField>

<ResponseField name="geojson_id" type="string">
  GeoJSON property to join on. Use a string for single property (e.g., "NAME") or array for composite key (e.g., \["STATE", "COUNTY"]).
</ResponseField>

<ResponseField name="area_id" type="string" required>
  Column name in data that matches geo\_id (e.g., "state\_id")
</ResponseField>

<ResponseField name="value" type="string" required>
  Column or expression for coloring the choropleth (e.g., "sum(sales)")
</ResponseField>

<ResponseField name="color_scale" type="array">
  Array of colors for the choropleth gradient. A single-color array auto-expands to \[background, color].
</ResponseField>

<ResponseField name="color_palette" type="array">
  Deprecated. Use `color_scale`.
</ResponseField>

<ResponseField name="min" type="number">
  Lower bound for the color scale. Values below this clamp to the first color in the scale. Defaults to the minimum value in the data.
</ResponseField>

<ResponseField name="max" type="number">
  Upper bound for the color scale. Values above this clamp to the last color in the scale. Defaults to the maximum value in the data.
</ResponseField>

<ResponseField name="midpoint" type="number">
  Anchor a specific value (typically 0) at the middle of a diverging color scale. Requires a color\_scale with 3 or more colors.
</ResponseField>

<ResponseField name="color_stops" type="array">
  Pin specific data values to specific colors, interpolating between them. Provide an array of value and color pairs. Values beyond the first and last breakpoint are clamped to the end colors. Takes precedence over color\_scale, min, max, and midpoint.
</ResponseField>

<ResponseField name="show_unmatched" type="boolean" default="true">
  Whether to show areas that do not have matching data
</ResponseField>

<ResponseField name="tooltip" type="boolean" default="true">
  Show tooltips on hover
</ResponseField>

<ResponseField name="tooltip_fields" type="array">
  Array of SQL expressions for additional fields to show in tooltip (e.g., \["category", "emissions"])
</ResponseField>

<ResponseField name="name_property" type="string">
  GeoJSON property to use for area name in tooltip (defaults to "NAME")
</ResponseField>

<ResponseField name="value_fmt" type="string" default="num">
  Format for values in tooltip. See [Value Formatting](/core-concepts/value-formatting) for available formats.
</ResponseField>

<ResponseField name="zoom_threshold" type="array">
  Zoom range \[min, max] where this layer is visible (e.g., \[0, 8] shows layer from zoom 0 to 8)
</ResponseField>

<ResponseField name="legend" type="boolean" default="true">
  Show legend for this layer
</ResponseField>

<ResponseField name="legend_label" type="string">
  Custom label for the legend (defaults to table name)
</ResponseField>

<ResponseField name="date_range" type="options group">
  Filter data to a time period. `date_range` is an OBJECT with `range` (the period) and optionally `date` (which column to filter on when the table has more than one). Shape: `date_range={ range="last 12 months" date="order_date" }`. `range` accepts predefined values (`last 7 days`, `month to date`), dynamic patterns (`Last 90 days`), custom windows (`2020-01-01 to 2023-03-01`), or partial ranges (`from 2020-01-01`, `until 2023-03-01`). Pass a plain string for `range` — the whole object is NOT a string.

  **Example:**

  ```
  date_range={
    range = "today"
    date = "string"
  }
  ```

  **Attributes:**

  * range: `string` - Time period to filter. Use presets like 'last 7 days', dynamic patterns like 'Last 90 days', custom ranges like '2020-01-01 to 2023-03-01', or partial ranges like 'from 2020-01-01'.
    * **Allowed values:**
      * `today`
      * `yesterday`
      * `last 7 days`
      * `last 30 days`
      * `last 3 months`
      * `last 6 months`
      * `last 12 months`
      * `previous week`
      * `previous month`
      * `previous quarter`
      * `previous year`
      * `this week`
      * `this month`
      * `this quarter`
      * `this year`
      * `next week`
      * `next month`
      * `next quarter`
      * `next year`
      * `week to date`
      * `month to date`
      * `quarter to date`
      * `year to date`
      * `all time`
  * date: `string` - Date column to filter on. Required when the data has multiple date columns.
</ResponseField>

<ResponseField name="where" type="string">
  Custom SQL WHERE condition to apply to the query. For date filters, use date\_range instead.
</ResponseField>

<ResponseField name="having" type="string">
  Custom SQL HAVING condition to apply to the query after GROUP BY
</ResponseField>

<ResponseField name="limit" type="number">
  Maximum number of rows to return from the query. Note: When used with tables, limit will disable subtotals to prevent incomplete subtotal rows.
</ResponseField>

<ResponseField name="order" type="string">
  Column name(s) with optional direction (e.g. "column\_name", "column\_name desc")
</ResponseField>

<ResponseField name="qualify" type="string">
  Custom SQL QUALIFY condition to filter windowed results
</ResponseField>

## Allowed Parents

* [map](/components/map)