## ScatterChart Scatter chart component Category: Charts ### Usage ScaltterChart is based on recharts [ScatterChart](https://recharts.org/en-US/api/ScatterChart) component: ```python import dash_mantine_components as dmc from .data import data1 component = dmc.ScatterChart( h=300, data=data1, dataKey={"x": "age", "y": "BMI"}, xAxisLabel="Age", yAxisLabel="BMI", ) ``` ### Data There are two datasets imported on this page. A single series `data1` and a multiple series `data2`: ```python data1 = [ { "color": "blue.5", "name": "Group 1", "data": [ {"age": 25, "BMI": 20}, {"age": 30, "BMI": 22}, {"age": 35, "BMI": 18}, {"age": 40, "BMI": 25}, {"age": 45, "BMI": 30}, {"age": 28, "BMI": 15}, {"age": 22, "BMI": 12}, {"age": 50, "BMI": 28}, {"age": 32, "BMI": 19}, {"age": 48, "BMI": 31}, {"age": 26, "BMI": 24}, {"age": 38, "BMI": 27}, {"age": 42, "BMI": 29}, {"age": 29, "BMI": 16}, {"age": 34, "BMI": 23}, {"age": 44, "BMI": 33}, {"age": 23, "BMI": 14}, {"age": 37, "BMI": 26}, {"age": 49, "BMI": 34}, {"age": 27, "BMI": 17}, {"age": 41, "BMI": 32}, {"age": 31, "BMI": 21}, {"age": 46, "BMI": 35}, {"age": 24, "BMI": 13}, {"age": 33, "BMI": 22}, {"age": 39, "BMI": 28}, {"age": 47, "BMI": 30}, {"age": 36, "BMI": 25}, {"age": 43, "BMI": 29}, {"age": 21, "BMI": 11} ] } ] ``` ```python data2 = [ { "color": "blue.5", "name": "Group 1", "data": [ {"age": 25, "BMI": 20}, {"age": 30, "BMI": 22}, {"age": 35, "BMI": 18}, {"age": 40, "BMI": 25}, {"age": 45, "BMI": 30}, {"age": 28, "BMI": 15}, {"age": 22, "BMI": 12}, {"age": 50, "BMI": 28}, {"age": 32, "BMI": 19}, {"age": 48, "BMI": 31}, {"age": 26, "BMI": 24}, {"age": 38, "BMI": 27}, {"age": 42, "BMI": 29}, {"age": 29, "BMI": 16}, {"age": 34, "BMI": 23}, {"age": 44, "BMI": 33}, {"age": 23, "BMI": 14}, {"age": 37, "BMI": 26}, {"age": 49, "BMI": 34}, {"age": 27, "BMI": 17}, {"age": 41, "BMI": 32}, {"age": 31, "BMI": 21}, {"age": 46, "BMI": 35}, {"age": 24, "BMI": 13}, {"age": 33, "BMI": 22}, {"age": 39, "BMI": 28}, {"age": 47, "BMI": 30}, {"age": 36, "BMI": 25}, {"age": 43, "BMI": 29}, {"age": 21, "BMI": 11} ] }, { "color": "red.5", "name": "Group 2", "data": [ {"age": 26, "BMI": 21}, {"age": 31, "BMI": 24}, {"age": 37, "BMI": 19}, {"age": 42, "BMI": 27}, {"age": 29, "BMI": 32}, {"age": 35, "BMI": 18}, {"age": 40, "BMI": 23}, {"age": 45, "BMI": 30}, {"age": 27, "BMI": 15}, {"age": 33, "BMI": 20}, {"age": 38, "BMI": 25}, {"age": 43, "BMI": 29}, {"age": 30, "BMI": 16}, {"age": 36, "BMI": 22}, {"age": 41, "BMI": 28}, {"age": 46, "BMI": 33}, {"age": 28, "BMI": 17}, {"age": 34, "BMI": 22}, {"age": 39, "BMI": 26}, {"age": 44, "BMI": 31}, {"age": 32, "BMI": 18}, {"age": 38, "BMI": 23}, {"age": 43, "BMI": 28}, {"age": 48, "BMI": 35}, {"age": 25, "BMI": 14}, {"age": 31, "BMI": 20}, {"age": 36, "BMI": 25}, {"age": 41, "BMI": 30}, {"age": 29, "BMI": 16} ] } ] ``` ### Multiple Series ```python import dash_mantine_components as dmc from .data import data2 component = dmc.ScatterChart( h=300, data=data2, dataKey={"x": "age", "y": "BMI"}, xAxisLabel="Age", yAxisLabel="BMI", ) ``` ### Legend To display chart legend, set `withLegend` prop. When one of the items in the legend is hovered, the corresponding data series is highlighted in the chart. ```python import dash_mantine_components as dmc from .data import data2 component = dmc.ScatterChart( h=300, data=data2, dataKey={"x": "age", "y": "BMI"}, xAxisLabel="Age", yAxisLabel="BMI", withLegend=True, ) ``` ### Legend position You can pass props down to recharts Legend component with `legendProps` prop. For example, setting the following will render the legend at the bottom of the chart and set its height to 50px: ```python legendProps={'verticalAlign': 'bottom', 'height': 50} ``` ```python import dash_mantine_components as dmc from .data import data2 component = dmc.ScatterChart( h=300, data=data2, dataKey={"x": "age", "y": "BMI"}, xAxisLabel="Age", yAxisLabel="BMI", withLegend=True, legendProps={"verticalAlign": "bottom", "height": 20}, ) ``` ### X and Y axis props Use `xAxisProps` and `yAxisProps` to pass props down to recharts `XAxis` and `YAxis` components. For example, these props can be used to change orientation of axis: ```python import dash_mantine_components as dmc from .data import data1 component = dmc.ScatterChart( h=300, data=data1, dataKey={"x": "age", "y": "BMI"}, tickLine="xy", yAxisProps={"tickMargin": 15, "orientation": "right"}, xAxisProps={"tickMargin": 15, "orientation": "top"}, ) ``` ### Point labels Set `pointLabels` prop to `x` or `y` to display labels on data points for the corresponding axis: ```python import dash_mantine_components as dmc from .data import data1 component = dmc.ScatterChart( h=300, data=data1, dataKey={"x": "age", "y": "BMI"}, tickLine="xy", xAxisLabel="Age", yAxisLabel="BMI", pointLabels="x", ) ``` ### Stroke dash array Set `strokeDasharray` prop to control the stroke dash array of the grid and cursor lines. The value represent the lengths of alternating dashes and gaps. For example, strokeDasharray="10 5" will render a dashed line with 10px dashes and 5px gaps. ```python import dash_mantine_components as dmc from .data import data1 component = dmc.ScatterChart( h=300, data=data1, dataKey={"x": "age", "y": "BMI"}, xAxisLabel="Age", yAxisLabel="BMI", strokeDasharray="15, 15", ) ``` ### Grid and text colors Use `--chart-grid-color` and `--chart-text-color` to change colors of grid lines and text within the chart. With CSS , you can change colors depending on color scheme. Learn more in the Theming section under [Colors.](/colors#colors-in-light-and-dark-mode) ```python import dash_mantine_components as dmc from .data import data1 component = dmc.ScatterChart( h=300, data=data1, dataKey={"x": "age", "y": "BMI"}, tickLine="xy", xAxisLabel="Age", yAxisLabel="BMI", className="chart-grid-text-colors", ) ``` ```css .chart-grid-text-colors { --chart-grid-color: var(--mantine-color-blue-5); --chart-text-color: var(--mantine-color-blue-8); } [data-mantine-color-scheme='dark'] .chart-grid-text-colors { --chart-grid-color: var(--mantine-color-blue-3); --chart-text-color: var(--mantine-color-blue-2); } ``` If your application has only one color scheme, you can use `gridColor` and `textColor` props instead of CSS variables: ```python dmc.ScatterChart( h=300, data=data1, dataKey={"x": "age", "y": "BMI"}, tickLine="xy", xAxisLabel="Age", yAxisLabel="BMI", gridColor="gray.5", textColor = "gray.9", ) ``` ### Units Set `unit` prop to render a unit label next to the y-axis ticks and tooltip values: ```python import dash_mantine_components as dmc spending_data = [ { "color": "cyan", "name": "Average monthly spending", "data": [ {"age": a, "average_monthly_spending": b} for a, b in zip( [ 25, 30, 35, 40, 45, 28, 22, 50, 32, 48, 26, 38, 42, 29, 34, 44, 23, 37, 49, 27, 41, 31, 46, 24, 33, 39, 47, 36, 43, 21, ], [ 1400, 2100, 1800, 2400, 2300, 1600, 1200, 3200, 1900, 2700, 1700, 2200, 2600, 1500, 2000, 2500, 1300, 2100, 2900, 1600, 2500, 1800, 2700, 1400, 2100, 2400, 2800, 2200, 2600, 1100, ], ) ], } ] component = dmc.ScatterChart( h=300, data=spending_data, dataKey={"x": "age", "y": "average_monthly_spending"}, yAxisProps={"domain": [800, 3500]}, unit={"y": "$"}, labels={"x": "Age", "y": "Spending"}, ) ``` ### Value formatter To format values in the tooltip and axis ticks, use `valueFormatter` prop. It accepts a function that takes number value as an argument and returns formatted value. Use two functions to format x and y values separately: Note: This example uses custom JavaScript defined in the assets folder. Learn more in the "Functions As Props" section of this document. ```python import dash_mantine_components as dmc spending_data = [ { "color": "cyan", "name": "Average monthly spending", "data": [ {"age": a, "average_monthly_spending": b} for a, b in zip( [ 25, 30, 35, 40, 45, 28, 22, 50, 32, 48, 26, 38, 42, 29, 34, 44, 23, 37, 49, 27, 41, 31, 46, 24, 33, 39, 47, 36, 43, 21, ], [ 1400, 2100, 1800, 2400, 2300, 1600, 1200, 3200, 1900, 2700, 1700, 2200, 2600, 1500, 2000, 2500, 1300, 2100, 2900, 1600, 2500, 1800, 2700, 1400, 2100, 2400, 2800, 2200, 2600, 1100, ], ) ], } ] component = dmc.ScatterChart( h=300, data=spending_data, dataKey={"x": "age", "y": "average_monthly_spending"}, yAxisProps={"domain": [800, 3500]}, valueFormatter={ "x": {"function": "formatYears"}, "y": {"function": "formatCurrency"} } ) ``` ```javascript var dmcfuncs = window.dashMantineFunctions = window.dashMantineFunctions || {}; dmcfuncs.formatCurrency = (value) => { return `$${new Intl.NumberFormat('en-US').format(value)}`; }; dmcfuncs.formatYears = (value) => { return `${value} years` }; ``` ### Tooltip labels To customize labels displayed in the tooltip, use `labels` prop: ```python import dash_mantine_components as dmc from .data import data1 component = dmc.ScatterChart( h=350, data=data1, dataKey={"x": "age", "y": "BMI"}, xAxisLabel="Age", yAxisLabel="BMI", labels={"x": "Age", "y": "Body Mass Index"}, ) ``` ### Custom tooltip Use the `tooltipProps` `content` prop to to pass custom tooltip renderer to recharts Tooltip component. For example: ```python tooltipProps={'content': {'functon': 'myFunction'}} ``` Note: This example uses custom JavaScript defined in the assets folder. Learn more in the "Functions As Props" section of this document. ```python import dash_mantine_components as dmc from .data import data1 component = dmc.ScatterChart( h=350, data=data1, dataKey={"x": "age", "y": "BMI"}, xAxisLabel="Age", yAxisLabel="BMI", tooltipProps={"content": {"function": "chartTooltip"}} ) ``` ```javascript var dmcfuncs = window.dashMantineFunctions = window.dashMantineFunctions || {}; var dmc = window.dash_mantine_components; dmcfuncs.chartTooltip = ({ label, payload }) => { if (!payload || payload.length === 0) return null; return React.createElement( dmc.Paper, { px: "md", py: "sm", withBorder: true, shadow: "md", radius: "md", }, [ React.createElement( dmc.Text, { key: "tooltip-label", fw: 500, mb: 5, }, label ), ...payload.map((item, index) => React.createElement( dmc.Text, { key: `item-${index}`, c: item.color, fz: "sm", }, `${item.name}: ${item.value}` ) ), ] ); }; ``` ### Remove tooltip To remove tooltip, set `withTooltip=False`. It also removes the cursor line and disables interactions with the chart. ```python import dash_mantine_components as dmc from .data import data1 component = dmc.ScatterChart( h=300, data=data1, dataKey={"x": "age", "y": "BMI"}, xAxisLabel="Age", yAxisLabel="BMI", withTooltip=False, ) ``` ### Tooltip animation By default, tooltip animation is disabled. To enable it, set `tooltipAnimationDuration` prop to a number of milliseconds to animate the tooltip position change. ```python import dash_mantine_components as dmc from .data import data1 component = dmc.ScatterChart( h=300, data=data1, dataKey={"x": "age", "y": "BMI"}, xAxisLabel="Age", yAxisLabel="BMI", tooltipAnimationDuration=200, ) ``` ### Points animation By default, the Recharts data animation is disabled. To enable and customize the animation, use `scatterProps` to pass properties to the Recharts `Scatter` component. ```python from random import randint import dash_mantine_components as dmc from dash import callback, Input, Output component = dmc.Box( [ dmc.Button("Update Chart", id="btn-scatterchart-animation"), dmc.ScatterChart( h=300, data=[{"color": "blue.5", "name": "Group 1", "data": [{}]}], scatterProps={ "isAnimationActive": True, "animationDuration": 500, "animationEasing": "ease-in-out", "animationBegin": 500, }, dataKey={"x": "x", "y": "y"}, xAxisLabel="X data", yAxisLabel="Y data", id="scatterchart-animation", ), ] ) @callback( Output("scatterchart-animation", "data"), Input("btn-scatterchart-animation", "n_clicks"), ) def update(n): return [ { "color": "blue.5", "name": "Group 1", "data": [ {"x": randint(1000, 4000), "y": randint(1000, 4000)} for _ in range(20) ], } ] ``` ### Reference lines Use `referenceLines` prop to render reference lines. Reference lines are always rendered behind the chart. ```python import dash_mantine_components as dmc from .data import data1 component = dmc.ScatterChart( h=300, data=data1, dataKey={"x": "age", "y": "BMI"}, xAxisLabel="Age", yAxisLabel="BMI", referenceLines=[ {"y": 14, "label": "Underweight ↓", "color": "red.7"}, {"y": 19, "label": "Normal weight", "color": "teal.7"}, {"y": 30, "label": "Overweight ↑", "color": "red.7"}, ], ) ``` ### clickData Use the `clickData` property in a callback to retrieve data from the most recent click event. To get the name of the clicked series, use the `clickSeriesName` property. ```python from dash import callback, Input, Output import dash_mantine_components as dmc from .data import data2 component = dmc.Group( [ dmc.ScatterChart( id="figure-scatterchart", h=300, data=data2, dataKey={"x": "age", "y": "BMI"}, xAxisLabel="Age", yAxisLabel="BMI", ), dmc.Text(id="clickdata-scatterchart1"), dmc.Text(id="clickdata-scatterchart2"), ] ) @callback( Output("clickdata-scatterchart1", "children"), Output("clickdata-scatterchart2", "children"), Input("figure-scatterchart", "clickData"), Input("figure-scatterchart", "clickSeriesName"), ) def update(data, name): return f"clickData: {data}", f"clickSeriesName: {name}" ``` ### hoverData Use the `hoverData` property in a callback to retrieve data from the most recent hover event. To get the name of the hovered series, use the `hoverSeriesName` property. ```python from dash import callback, Input, Output import dash_mantine_components as dmc from .data import data2 component = dmc.Group( [ dmc.ScatterChart( id="figure-scatterchart-hover", h=300, data=data2, dataKey={"x": "age", "y": "BMI"}, xAxisLabel="Age", yAxisLabel="BMI", withTooltip=False, ), dmc.Text(id="hoverdata-scatterchart1"), dmc.Text(id="hoverdata-scatterchart2"), ] ) @callback( Output("hoverdata-scatterchart1", "children"), Output("hoverdata-scatterchart2", "children"), Input("figure-scatterchart-hover", "hoverData"), Input("figure-scatterchart-hover", "hoverSeriesName"), ) def update(data, name): return f"hoverData: {data}", f"hoverSeriesName: {name}" ``` ### Styles API This component supports Styles API. With Styles API, you can customize styles of any inner element. See the Styling and Theming sections of these docs for more information. #### ScatterChart selectors | Selector | Static selector | Description | |-------------------|---------------------------------|-------------------------------------------------| | root | .mantine-ScatterChart-root | Root element | | scatter | .mantine-ScatterChart-scatter | Recharts Scatter component | | axis | .mantine-ScatterChart-axis | X and Y axis of the chart | | container | .mantine-ScatterChart-container | Recharts ResponsiveContainer component | | grid | .mantine-ScatterChart-grid | Recharts CartesianGrid component | | legend | .mantine-ScatterChart-legend | Legend root element | | legendItem | .mantine-ScatterChart-legendItem | Legend item representing data series | | legendItemColor | .mantine-ScatterChart-legendItemColor | Legend item color | | legendItemName | .mantine-ScatterChart-legendItemName | Legend item name | | tooltip | .mantine-ScatterChart-tooltip | Tooltip root element | | tooltipBody | .mantine-ScatterChart-tooltipBody | Tooltip wrapper around all items | | tooltipItem | .mantine-ScatterChart-tooltipItem | Tooltip item representing data series | | tooltipItemBody | .mantine-ScatterChart-tooltipItemBody | Tooltip item wrapper around item color and name | | tooltipItemColor | .mantine-ScatterChart-tooltipItemColor | Tooltip item color | | tooltipItemName | .mantine-ScatterChart-tooltipItemName | Tooltip item name | | tooltipItemData | .mantine-ScatterChart-tooltipItemData | Tooltip item data | | tooltipLabel | .mantine-ScatterChart-tooltipLabel | Label of the tooltip | | referenceLine | .mantine-ScatterChart-referenceLine | Reference line | | axisLabel | .mantine-ScatterChart-axisLabel | X and Y axis labels | #### ScatterChart CSS variables | Selector | Variable | Description | |----------------|--------------------|------------------------------------------| | root | --chart-grid-color | Controls color of the grid and cursor lines | | | --chart-text-color | Controls color of the axis labels | ### Keyword Arguments #### ScatterChart - id (string; optional): Unique ID to identify this component in Dash callbacks. - aria-* (string; optional): Wild card aria attributes. - attributes (boolean | number | string | dict | list; optional): Passes attributes to inner elements of a component. See Styles API docs. - className (string; optional): Class added to the root element, if applicable. - classNames (dict; optional): Adds custom CSS class names to inner elements of a component. See Styles API docs. - clickData (dict with strings as keys and values of type boolean | number | string | dict | list; optional): Click data. - clickSeriesName (dict with strings as keys and values of type boolean | number | string | dict | list; optional): Name of the series that was clicked. - darkHidden (boolean; optional): Determines whether component should be hidden in dark color scheme with `display: none`. - data (list of dicts; required): Data that is used to build the chart. `data` is a list of dicts with keys: - data-* (string; optional): Wild card data attributes. - dataKey (dict; required): Keys that should be used to retrieve data from the data array on x and y axis. `dataKey` is a dict with keys: - gridAxis (a value equal to: 'none', 'x', 'y', 'xy'; optional): Specifies which lines should be displayed in the grid, `'x'` by default. - gridColor (optional): Color of the grid and cursor lines, by default depends on color scheme. - gridProps (dict; optional): Props passed down to the `CartesianGrid` component. - hiddenFrom (string; optional): Breakpoint above which the component is hidden with `display: none`. - hoverData (dict with strings as keys and values of type boolean | number | string | dict | list; optional): Hover data. - hoverSeriesName (dict with strings as keys and values of type boolean | number | string | dict | list; optional): Name of the series that is hovered. - labels (dict; optional): Labels that should be used instead of keys names in the tooltip. `labels` is a dict with keys: - legendProps (dict; optional): Props passed down to the `Legend` component. - lightHidden (boolean; optional): Determines whether component should be hidden in light color scheme with `display: none`. - loading_state (dict; optional): Object that holds the loading state object coming from dash-renderer. For use with dash<3. `loading_state` is a dict with keys: - mod (string | dict | list of string | dicts; optional): Element modifiers transformed into `data-` attributes. For example: "xl" or {"data-size": "xl"}. Can also be a list of strings or dicts for multiple modifiers. Falsy values are removed. - orientation (a value equal to: 'horizontal', 'vertical'; optional): Chart orientation, `'horizontal'` by default. - pointLabels (a value equal to: 'x', 'y'; optional): If set, displays labels next to points for the given axis. - referenceLines (list of dicts; optional): Reference lines that should be displayed on the chart. - rightYAxisLabel (boolean | number | string | dict | list; optional): Props passed down to the YAxis recharts component rendered on the right side. - rightYAxisProps (boolean | number | string | dict | list; optional): Props passed down to the YAxis recharts component rendered on the right side. - scatterChartProps (dict; optional): Props passed down to recharts `ScatterChart` component. - scatterProps (dict; optional): Props passed down to recharts `Scatter` component. - strokeDasharray (string | number; optional): Dash array for the grid lines and cursor, `'5 5'` by default. - styles (boolean | number | string | dict | list; optional): Adds inline styles directly to inner elements of a component. See Styles API docs. - tabIndex (number; optional): tab-index. - textColor (optional): Color of the text displayed inside the chart, `'dimmed'` by default. - tickLine (a value equal to: 'none', 'x', 'y', 'xy'; optional): Specifies which axis should have tick line, `'y'` by default. - tooltipAnimationDuration (number; optional): Tooltip position animation duration in ms, `0` by default. - tooltipProps (dict; optional): Props passed down to the `Tooltip` component. - unit (dict; optional): Units displayed after value on axis and inside the tooltip. `unit` is a dict with keys: - valueFormatter (boolean | number | string | dict | list; optional): A function to format values on Y axis and inside the tooltip. See https://www.dash-mantine-components.com/functions-as-props. - variant (string; optional): variant. - visibleFrom (string; optional): Breakpoint below which the component is hidden with `display: none`. - withLegend (boolean; optional): Determines whether chart legend should be displayed, `False` by default. - withRightYAxis (boolean; optional): Determines whether additional y-axis should be displayed on the right side of the chart, False by default. - withTooltip (boolean; optional): Determines whether chart tooltip should be displayed, `True` by default. - withXAxis (boolean; optional): Determines whether x-axis should be hidden, `True` by default. - withYAxis (boolean; optional): Determines whether y-axis should be hidden, `True` by default. - xAxisLabel (string; optional): A label to display below the x-axis. - xAxisProps (dict; optional): Props passed down to the `XAxis` recharts component. - yAxisLabel (string; optional): A label to display next to the y-axis. - yAxisProps (dict; optional): Props passed down to the `YAxis` recharts component.