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

# Heat Map

> Interactive market-performance map grouped by symbol, sector, size, and percentage change.

Heat Map turns a market universe into an interactive visual overview. Tile size, grouping, and color help users understand where performance and market weight are concentrated before opening a specific security.

<iframe data-widget-embed-slot="heat-map" src="https://h5.ainvest.com/frontPage/regular/widgets-container/heat-map-open-widget-preview.html" title="AInvest Heat Map widget preview" style={{ display: "block", width: "100%", height: "min(80vh, 900px)", minHeight: "720px", maxHeight: "900px", border: 0, borderRadius: "12px", overflow: "hidden" }} loading="lazy" allow="clipboard-write; fullscreen" allowFullScreen referrerPolicy="strict-origin-when-cross-origin" />

## Properties

### Common properties

| Name              | Type                         | Required | Default      | Description                                                                |
| ----------------- | ---------------------------- | -------- | ------------ | -------------------------------------------------------------------------- |
| `theme`           | `"light" or "dark"`          | No       | `light`      | Visual theme applied inside the widget iframe.                             |
| `locale`          | `string`                     | No       | `en`         | Locale used by labels, formatting, and component copy when supported.      |
| `colorPreference` | `"GreenForUp" or "RedForUp"` | No       | `GreenForUp` | Controls whether green or red represents positive price movement.          |
| `autoHeight`      | `boolean`                    | No       | `true`       | Enables ResizeObserver-driven iframe height updates through `postMessage`. |

### Widget properties

| Name         | Type                                                                                                                                                                                                                                                            | Required | Default        | Description                                |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------- | ------------------------------------------ |
| `marketType` | `"Stock" or "ETF" or "Crypto"`                                                                                                                                                                                                                                  | No       | `Stock`        | Market tab and universe type.              |
| `dataSource` | `"sp500" or "nasdaq100" or "nasdaq_composite" or "nyse_composite" or "all_stocks" or "dji" or "etf" or "crypto" or "crypto_ex_btc"`                                                                                                                             | No       | `sp500`        | Dataset used to build the heatmap.         |
| `sizeBy`     | `"market_cap" or "aum" or "mono_size"`                                                                                                                                                                                                                          | No       | `market_cap`   | Metric used to size each tile.             |
| `colorBy`    | `"change_pct_1h" or "change_pct_4h" or "change_pct_d" or "change_pct_24h" or "change_pct_w" or "change_pct_m" or "change_pct_3m" or "change_pct_6m" or "change_pct_ytd" or "change_pct_1y" or "pre_market_chg" or "post_market_chg" or "volatility_d" or "gap"` | No       | `change_pct_d` | Metric used for tile color.                |
| `groupBy`    | `"None" or "sector" or "asset_class"`                                                                                                                                                                                                                           | No       | `sector`       | Grouping dimension for the heatmap layout. |
| `showTab`    | `boolean`                                                                                                                                                                                                                                                       | No       | `true`         | Shows or hides the market type tabs.       |
| `title`      | `string`                                                                                                                                                                                                                                                        | No       | \`\`           | Optional title rendered by the widget.     |

## Events

| Event              | Payload                                        | Description                             |
| ------------------ | ---------------------------------------------- | --------------------------------------- |
| `marketTypeChange` | `{ marketType: "Stock" or "ETF" or "Crypto" }` | Fired when the market type tab changes. |

## When to use Heat Map

* Market and sector overview pages where visual pattern recognition matters
* Index pages that need market-cap-weighted performance context
* Discovery dashboards where selecting a tile opens deeper analysis
* Editorial pages that explain broad participation or sector divergence

Use [Top List](/widgets/api-reference/top-list) when users need exact ranking, sorting, and tabular comparison.

## Core experience

The map should identify its universe, grouping dimension, tile-size metric, color metric, session, and last-update time. Keep a visible legend and display a numeric value inside or alongside each selectable tile.

Tile area and color must represent separate, clearly labeled metrics. Avoid making small tiles impossible to focus, read, or select.

## Data and visualization states

Support loading, empty-universe, no-filter-results, delayed-data, market-closed, entitlement, reconnecting, and error states. Keep the legend synchronized with the actual color scale after filters or metrics change.

If values are unavailable for part of the universe, use a neutral unavailable state rather than mapping missing data to zero performance.

## Responsive behavior

At smaller widths, reduce label density while preserving numeric values for focused or selected tiles. Provide a list or detail panel for tiles that are too small to label. Keep filters and the legend visible without creating horizontal page scrolling.

## Accessibility

* Color must not be the only way performance is communicated.
* Give each tile an accessible label containing symbol, group, and numeric value.
* Provide keyboard navigation and visible focus for selectable tiles.
* Use a color scale with sufficient contrast and a neutral midpoint.
* Offer an equivalent textual or tabular summary when required.

## Best practices

* Choose a familiar market universe and label it prominently.
* Keep the color range stable enough for meaningful comparison.
* Avoid excessive filters that leave only a few disconnected tiles.
* Pair tile selection with a quote or chart for further analysis.
* Test color contrast, missing data, small tiles, and empty filters.

## Related widgets

* [Top List](/widgets/api-reference/top-list) adds an exact ranking beside the visual overview.
* [Super Chart](/widgets/api-reference/super-chart) opens a selected tile in a detailed chart.