> ## 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.

# Scatter plot

> Plot two metrics on X and Y axes to spot correlations, outliers, and clusters.

A **scatter plot** puts each row of the data on a two-dimensional grid — the X-axis is one metric, the Y-axis is another. Optionally, a third metric can size each dot (bubble size). Scatter plots are best for spotting correlations, outliers, and clusters between two or three related numeric measures.

## When to use a scatter plot

* **Correlation between two metrics** — for example, Spend vs Conversions, or CPC vs CTR.
* **Outlier detection** — dots far from the main cluster are worth investigating.
* **Adding a third dimension** with bubble size — for example, X = Spend, Y = Conversions, bubble = Impressions.

For a simple ranked comparison, a [column chart](/widgets/widget-library/chart-widgets/column-chart) is easier to read.

## Configure a scatter plot

### Mandatory fields

<Steps>
  <Step title="Pick a data source">
    In the **Data sources** section, select the data source to include. Scatter plots support both ad and non-ad data sources.
  </Step>

  <Step title="Pick a Y-axis metric">
    Click **Edit** on the Y-axis 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. New custom metrics can be created directly from the picker panel without leaving the chart widget. The active metric renders as the vertical (Y) position of each dot — for example, Conversions.
  </Step>

  <Step title="Pick an X-axis metric">
    Click **Edit** on the X-axis 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 horizontal (X) position of each dot — for example, Spend. Each dot represents one row of the underlying data plotted at (X, Y).
  </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. New custom breakdowns can be created directly from the picker panel without leaving the chart widget. The active breakdown controls what each dot represents — for example, Group by Campaign name produces one dot per campaign. To show a single aggregated dot across the whole visible period, select the **No grouping** option.

    The Group by cannot be a date breakdown — dates aren't valid Group by choices on scatter plots.
  </Step>
</Steps>

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

### Optional fields

* **Bubble size** — add a third metric that sizes each dot (for example, size dots by Impressions). Leave blank for uniform dot size.
* **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).
* **Grid** — toggle background gridlines.
* **Chart controls** — toggle whether Chart controls render on this widget. On by default.

## Chart controls

Chart controls are toggled on or off per widget from the **Chart controls** switch in the widget settings panel. When off, Chart controls don't render on the widget; when on, the dropdowns configured below appear on the widget.

Some key settings can be updated directly from the widget header without opening the settings panel. The **Chart controls** on a scatter plot expose:

* **Chart type** — a switcher on the left of the widget header to change to another chart type.
* **Y-axis** — swap the vertical metric inline.
* **X-axis** — swap the horizontal metric inline.
* **Group by** — change what each dot represents inline.
* **Bubble size by** — swap or clear the bubble-size metric inline.

Changes made in the Chart controls **aren't saved automatically** — click **Save dashboard** to persist them. Chart controls are read-only when viewing a shared dashboard. In shared dashboards, Chart controls show only the items selected in each field, matching what the dashboard owner configured.

## Dot limit

Scatter plots render up to **100 dots** by default. When the Group by produces more than 100 dots, the widget truncates to the top 100. Narrow with a widget filter or pick a coarser Group by to keep the set within the limit.

## Reading a scatter plot

* **Positive correlation** — dots trend from bottom-left to top-right (more X, more Y).
* **Negative correlation** — dots trend from top-left to bottom-right (more X, less Y).
* **No correlation** — dots scatter without a clear pattern.
* **Outliers** — dots far from the main cluster deserve investigation.

Hover on any dot to see the item's identity and exact values.

## Comparison mode

**Scatter plots do not render comparison values.** Even when the Compare toggle is on, the scatter plot 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, Scatter plot widgets have style options unique to this widget type:

* **Color type** — toggle between **Solid** and **Gradient** for the dot fill.
* **Data text** — when data labels are enabled, the label color (HEX), stroke color (HEX + opacity), and stroke weight are configurable.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The plot is empty ('No data available')">
    Confirm both the X-axis and Y-axis metrics produce values in the current date range, and that the Group by returns at least one row. See [Data not loading](/troubleshooting/data-not-loading).
  </Accordion>

  <Accordion title="All dots are stacked on top of each other">
    The chosen metrics have a very narrow range — most rows sit at the same (X, Y). Try metrics with more variation, or apply a widget filter to narrow the range.
  </Accordion>

  <Accordion title="Bubbles are hard to distinguish">
    A single large row can compress every other bubble. Apply a widget filter to exclude the outlier, or pick a bubble-size metric with less range.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Column chart" href="/widgets/widget-library/chart-widgets/column-chart">
    Ranked comparisons across a smaller number of categories.
  </Card>

  <Card title="Line chart" href="/widgets/widget-library/chart-widgets/line-chart">
    Trends over time.
  </Card>

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