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

# Treemap

> Display a treemap of nested rectangles sized by value

```liquid theme={null}
{% treemap
    data="demo.daily_orders"
    category="category"
    value="sum(total_sales)"
/%}
```

## Examples

### Basic Usage

```liquid theme={null}
{% treemap
    data="demo.daily_orders"
    category="category"
    value="sum(total_sales)"
/%}
```

### Grouped Treemap

```liquid theme={null}
{% treemap
    data="demo.order_details"
    group="category"
    category="item_name"
    value="sum(quantity)"
    title="Quantity by Category and Item"
/%}
```

### With Values on Labels

```liquid theme={null}
{% treemap
    data="demo.daily_orders"
    category="category"
    value="sum(total_sales)"
    title="Sales by Category"
    value_fmt="usd"
    show_values=true
/%}
```

### With Custom Colors

```liquid theme={null}
{% treemap
    data="demo.daily_orders"
    category="category"
    value="sum(total_sales)"
    title="Sales by Category"
    chart_options={
        color_palette = ["#0d0887", "#6300a7", "#a62098", "#d5546e", "#f68d45", "#fcd225", "#f0f921"]
    }
/%}
```

### With Raw ECharts Overrides

```liquid theme={null}
{% treemap
    data="demo.daily_orders"
    category="category"
    value="sum(total_sales)"
    echarts_series_options={
        itemStyle={ borderRadius=8 gapWidth=4 }
    }
/%}
```

## Attributes

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

<ResponseField name="filters" type="array">
  IDs of filters to apply to the query
</ResponseField>

<ResponseField name="date_range" type="options group">
  Use date\_range to filter data for specific time periods. Accepts predefined ranges (e.g., "last 12 months"), dynamic ranges (e.g., "Last 90 days"), custom date ranges (e.g., "2020-01-01 to 2023-03-01"), or partial ranges (e.g., "from 2020-01-01", "until 2023-03-01")

  **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="category" type="string" required>
  Column name for categories (one rectangle per category)
</ResponseField>

<ResponseField name="group" type="string">
  Column name for grouping categories into parent rectangles (optional)
</ResponseField>

<ResponseField name="value" type="string" required>
  Column name for values (rectangle sizes)
</ResponseField>

<ResponseField name="title" type="string">
  Title to display above the component
</ResponseField>

<ResponseField name="subtitle" type="string">
  Subtitle to display below the title
</ResponseField>

<ResponseField name="info" type="string">
  Information tooltip text (can only be used with title). Displays an info icon next to the title.
</ResponseField>

<ResponseField name="info_link" type="string">
  URL to link the info text to (can only be used with info)
</ResponseField>

<ResponseField name="info_link_title" type="string">
  Create a custom link title for the info link, placed after the info text (can only be used with info\_link)
</ResponseField>

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

<ResponseField name="show_values" type="boolean" default="false">
  Show formatted values on rectangle labels
</ResponseField>

<ResponseField name="chart_options" type="options group">
  Chart configuration options

  **Example:**

  ```
  chart_options={
    color_palette = ["value1", "value2"]
    series_colors = {
      "key1" = "value1"
      "key2" = "value2"
    }
  }
  ```

  **Attributes:**

  * color\_palette: `array of strings`
  * series\_colors: `map of key-value pairs`
</ResponseField>

<ResponseField name="echarts_options" type="map">
  Raw [ECharts options](https://echarts.apache.org/en/option.html) deep-merged over the chart's final configuration. Use for anything the structured props do not expose — `graphic`, `visualMap`, tooltip styling, and so on. Partial overrides win key-by-key without clobbering Studio's computed siblings. For overrides scoped to the data series, use `echarts_series_options`.

  **Example:**

  ```
  echarts_options={
      tooltip={ position="top" }
      graphic=[{ type="text" }]
  }
  ```
</ResponseField>

<ResponseField name="echarts_series_options" type="map">
  Raw [ECharts series options](https://echarts.apache.org/en/option.html#series) deep-merged into the chart series. Use for series-level styling the structured props do not expose.

  **Example:**

  ```
  echarts_series_options={
      itemStyle={ borderRadius=8 }
  }
  ```
</ResponseField>

<ResponseField name="refresh_interval" type="number">
  Time in seconds between automatic data refreshes (minimum 60). Overrides the page-level auto-refresh setting for this component.
</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>

<ResponseField name="width" type="number">
  Set the width of this component (in percent) relative to the page width
</ResponseField>

<ResponseField name="height" type="number">
  Set a fixed height for the chart in pixels
</ResponseField>

<ResponseField name="connect_group" type="string">
  Link this chart to others sharing the same id, syncing their tooltips, axis-pointer, and zoom
</ResponseField>

<ResponseField name="tooltip_fields" type="array">
  Extra columns to include in the tooltip on hover. Each entry is `{ value, label?, fmt?, color_by_sign?, down_is_good? }`. See the [tooltip fields guide](/components/tooltip-fields) for examples.
</ResponseField>