[charts] Support unknown color in colorscale

alexfauquette · alexfauquette · commit 2709bcebb893 · 2026-06-15T15:22:37.000+02:00
diff --git a/docs/data/charts/map/ColorScaleMapShape.js b/docs/data/charts/map/ColorScaleMapShape.js
@@ -1,7 +1,10 @@
 import * as React from 'react';
+import { useTheme } from '@mui/material/styles';
 import Box from '@mui/material/Box';
 import Stack from '@mui/material/Stack';
 import Typography from '@mui/material/Typography';
+import Checkbox from '@mui/material/Checkbox';
+import FormControlLabel from '@mui/material/FormControlLabel';
 import ToggleButtonGroup from '@mui/material/ToggleButtonGroup';
 import ToggleButton from '@mui/material/ToggleButton';
 import { interpolateBlues } from 'd3-scale-chromatic';
@@ -31,20 +34,35 @@ const data = Object.keys(countryData).map((code) => ({
 
 export default function ColorScaleMapShape() {
   const [colorMap, setColorMap] = React.useState('continuous');
+  const [unknownColor, setUnknownColor] = React.useState(true);
 
+  const theme = useTheme();
   return (
     <Stack spacing={2} sx={{ width: '100%', maxWidth: 800 }}>
-      <ToggleButtonGroup
-        color="primary"
-        size="small"
-        exclusive
-        value={colorMap}
-        onChange={(_, value) => value && setColorMap(value)}
-        aria-label="color map"
+      <Stack
+        direction="row"
+        sx={{ alignItems: 'center', justifyContent: 'space-between' }}
       >
-        <ToggleButton value="continuous">continuous</ToggleButton>
-        <ToggleButton value="piecewise">piecewise</ToggleButton>
-      </ToggleButtonGroup>
+        <ToggleButtonGroup
+          color="primary"
+          size="small"
+          exclusive
+          value={colorMap}
+          onChange={(_, value) => value && setColorMap(value)}
+          aria-label="color map"
+        >
+          <ToggleButton value="continuous">continuous</ToggleButton>
+          <ToggleButton value="piecewise">piecewise</ToggleButton>
+        </ToggleButtonGroup>
+        <FormControlLabel
+          checked={unknownColor}
+          control={
+            <Checkbox onChange={(event) => setUnknownColor(event.target.checked)} />
+          }
+          label="Use unknown color"
+          labelPlacement="end"
+        />
+      </Stack>
       <Typography variant="body2" component="h6" sx={{ textAlign: 'end' }}>
         Share of the population using the Internet in 2020
       </Typography>
@@ -74,11 +92,13 @@ export default function ColorScaleMapShape() {
                       min: 0,
                       max: 100,
                       color: ['#e3f2fd', '#0d47a1'],
+                      unknownColor: unknownColor ? 'gray' : undefined,
                     }
                   : {
                       type: 'piecewise',
                       thresholds: [25, 50, 75],
                       colors: [0.25, 0.5, 0.75, 1].map(interpolateBlues),
+                      unknownColor: unknownColor ? 'gray' : undefined,
                     },
             },
           ]}
diff --git a/docs/data/charts/map/ColorScaleMapShape.tsx b/docs/data/charts/map/ColorScaleMapShape.tsx
@@ -1,7 +1,10 @@
 import * as React from 'react';
+import { useTheme } from '@mui/material/styles';
 import Box from '@mui/material/Box';
 import Stack from '@mui/material/Stack';
 import Typography from '@mui/material/Typography';
+import Checkbox from '@mui/material/Checkbox';
+import FormControlLabel from '@mui/material/FormControlLabel';
 import ToggleButtonGroup from '@mui/material/ToggleButtonGroup';
 import ToggleButton from '@mui/material/ToggleButton';
 import { interpolateBlues } from 'd3-scale-chromatic';
@@ -36,20 +39,35 @@ type ColorMapType = 'continuous' | 'piecewise';
 
 export default function ColorScaleMapShape() {
   const [colorMap, setColorMap] = React.useState<ColorMapType>('continuous');
+  const [unknownColor, setUnknownColor] = React.useState(true);
 
+  const theme = useTheme();
   return (
     <Stack spacing={2} sx={{ width: '100%', maxWidth: 800 }}>
-      <ToggleButtonGroup
-        color="primary"
-        size="small"
-        exclusive
-        value={colorMap}
-        onChange={(_, value: ColorMapType | null) => value && setColorMap(value)}
-        aria-label="color map"
+      <Stack
+        direction="row"
+        sx={{ alignItems: 'center', justifyContent: 'space-between' }}
       >
-        <ToggleButton value="continuous">continuous</ToggleButton>
-        <ToggleButton value="piecewise">piecewise</ToggleButton>
-      </ToggleButtonGroup>
+        <ToggleButtonGroup
+          color="primary"
+          size="small"
+          exclusive
+          value={colorMap}
+          onChange={(_, value: ColorMapType | null) => value && setColorMap(value)}
+          aria-label="color map"
+        >
+          <ToggleButton value="continuous">continuous</ToggleButton>
+          <ToggleButton value="piecewise">piecewise</ToggleButton>
+        </ToggleButtonGroup>
+        <FormControlLabel
+          checked={unknownColor}
+          control={
+            <Checkbox onChange={(event) => setUnknownColor(event.target.checked)} />
+          }
+          label="Use unknown color"
+          labelPlacement="end"
+        />
+      </Stack>
       <Typography variant="body2" component="h6" sx={{ textAlign: 'end' }}>
         Share of the population using the Internet in 2020
       </Typography>
@@ -79,11 +97,13 @@ export default function ColorScaleMapShape() {
                       min: 0,
                       max: 100,
                       color: ['#e3f2fd', '#0d47a1'],
+                      unknownColor: unknownColor ? 'gray' : undefined,
                     }
                   : {
                       type: 'piecewise',
                       thresholds: [25, 50, 75],
                       colors: [0.25, 0.5, 0.75, 1].map(interpolateBlues),
+                      unknownColor: unknownColor ? 'gray' : undefined,
                     },
             },
           ]}
diff --git a/docs/data/charts/map/map.md b/docs/data/charts/map/map.md
@@ -111,6 +111,9 @@ When no `colorValue` is provided, the item's `value` is used as a fallback.
 
 If several `zAxis` are defined, the series can target one explicitly with the `colorAxisId` property.
 
+By default shapes with unknown values are ignored.
+Specify the `unknownColor` property in the `colorMap` to render them.
+
 {{"demo": "ColorScaleMapShape.js"}}
 
 ## Using a dataset
diff --git a/docs/data/charts/styling/styling.md b/docs/data/charts/styling/styling.md
@@ -50,6 +50,7 @@ See the dedicated documentation sections for each chart component to learn more
 - [Bar charts](/x/react-charts/bars/#color-scale)
 - [Line charts](/x/react-charts/lines/#color-scale)
 - [Bubble charts](/x/react-charts/bubble/#mapping-data-to-color)
+- [Maps](/x/react-charts/map/#mapping-values-to-colors)[<span class="plan-premium"></span>](/x/introduction/licensing/#premium-plan 'Premium plan')
 
 The `colorMap` property accepts three kinds of objects for color maps: piecewise, continuous, and ordinal.
 
@@ -62,6 +63,7 @@ You can configure a piecewise color map with an array of _n_ `thresholds` values
   type: 'piecewise';
   thresholds: Value[];
   colors: string[];
+  unknownColor?: string;
 }
 ```
 
@@ -82,6 +84,7 @@ By default, the `min`-`max` range is 0-100.
   min?: Value;
   max?: Value;
   color: [string, string] | ((t: number) => string);
+  unknownColor?: string;
 }
 ```
 
diff --git a/packages/x-charts-premium/src/BarChartPremium/RangeBar/seriesConfig/getColor.ts b/packages/x-charts-premium/src/BarChartPremium/RangeBar/seriesConfig/getColor.ts
@@ -14,9 +14,9 @@ const getColor: ColorProcessor<'rangeBar'> = (series, xAxis, yAxis) => {
       }
 
       const value = bandValues[dataIndex];
-      const color = value === null ? getSeriesColor({ value, dataIndex }) : bandColorScale(value);
+      const color = bandColorScale(value);
 
-      if (color === null) {
+      if (typeof color !== 'string') {
         return getSeriesColor({ value, dataIndex });
       }
 
diff --git a/packages/x-charts-premium/src/Map/MapShapePlot.tsx b/packages/x-charts-premium/src/Map/MapShapePlot.tsx
@@ -73,7 +73,8 @@ export function MapShapePlot(props: MapShapePlotProps) {
                   {featureIndexes.map((featureIndex) => {
                     const feature = geoData.features[featureIndex];
                     const d = path(feature);
-                    if (!d) {
+                    const color = fill ?? colorGetter(dataIndex);
+                    if (!d || color === null) {
                       return null;
                     }
                     return (
@@ -82,7 +83,7 @@ export function MapShapePlot(props: MapShapePlotProps) {
                         seriesId={id}
                         dataIndex={dataIndex}
                         d={d}
-                        color={fill ?? colorGetter(dataIndex)}
+                        color={color}
                         stroke={stroke}
                         strokeWidth={strokeWidth}
                       />
diff --git a/packages/x-charts-premium/src/Map/seriesConfig/getColor.ts b/packages/x-charts-premium/src/Map/seriesConfig/getColor.ts
@@ -9,17 +9,15 @@ const getColor: ColorProcessor<'mapShape'> = (series, _mainAxis, _secondaryAxis,
         return series.color;
       }
       const item = series.data[dataIndex];
-      if (item === undefined) {
-        return series.color;
+
+      if (item.color !== undefined) {
+        return item.color;
       }
       const scaleInput = item.colorValue ?? item.value;
-      if (scaleInput != null) {
-        const color = colorScale(scaleInput);
-        if (color !== null) {
-          return color;
-        }
-      }
-      return item.color ?? series.color;
+
+      const color = colorScale(scaleInput);
+
+      return color;
     };
   }
 
diff --git a/packages/x-charts/src/ScatterChart/seriesConfig/getColor.ts b/packages/x-charts/src/ScatterChart/seriesConfig/getColor.ts
@@ -20,11 +20,8 @@ const getColor: ColorProcessor<'scatter'> = (series, xAxis, yAxis, zAxis) => {
         }
       }
       const value = series.data[dataIndex];
-      const color =
-        value === null
-          ? getSeriesColor({ value, dataIndex })
-          : zColorScale(value.colorValue ?? value.z);
-      if (color === null) {
+      const color = zColorScale(value.colorValue ?? value.z);
+      if (typeof color !== 'string') {
         return getSeriesColor({ value, dataIndex });
       }
       return color;
@@ -37,8 +34,8 @@ const getColor: ColorProcessor<'scatter'> = (series, xAxis, yAxis, zAxis) => {
         return series.color;
       }
       const value = series.data[dataIndex];
-      const color = value === null ? getSeriesColor({ value, dataIndex }) : yColorScale(value.y);
-      if (color === null) {
+      const color = yColorScale(value.y);
+      if (typeof color !== 'string') {
         return getSeriesColor({ value, dataIndex });
       }
       return color;
@@ -51,8 +48,8 @@ const getColor: ColorProcessor<'scatter'> = (series, xAxis, yAxis, zAxis) => {
         return series.color;
       }
       const value = series.data[dataIndex];
-      const color = value === null ? getSeriesColor({ value, dataIndex }) : xColorScale(value.x);
-      if (color === null) {
+      const color = xColorScale(value.x);
+      if (typeof color !== 'string') {
         return getSeriesColor({ value, dataIndex });
       }
       return color;
diff --git a/packages/x-charts/src/internals/colorScale.ts b/packages/x-charts/src/internals/colorScale.ts
@@ -14,10 +14,12 @@ export function getSequentialColorScale<Value extends number | Date>(
   config: ContinuousColorConfig<Value> | PiecewiseColorConfig<Value>,
 ) {
   if (config.type === 'piecewise') {
-    return scaleThreshold(config.thresholds, config.colors);
+    return scaleThreshold(config.thresholds, config.colors).unknown(config.unknownColor ?? null);
   }
 
-  return scaleSequential([config.min ?? 0, config.max ?? 100], config.color);
+  return scaleSequential([config.min ?? 0, config.max ?? 100], config.color).unknown(
+    config.unknownColor ?? null,
+  );
 }
 
 export function getOrdinalColorScale<Value extends number | Date | string>(
diff --git a/packages/x-charts/src/internals/plugins/corePlugins/useChartSeriesConfig/types/colorProcessor.types.ts b/packages/x-charts/src/internals/plugins/corePlugins/useChartSeriesConfig/types/colorProcessor.types.ts
@@ -18,7 +18,9 @@ export type ColorGetter<SeriesType extends ChartSeriesType> = SeriesType extends
   ? (dataIndex: number) => string
   : SeriesType extends 'heatmap'
     ? (value: number | null) => string
-    : (dataIndex?: number) => string;
+    : SeriesType extends 'mapShape'
+      ? (dataIndex?: number) => string | null
+      : (dataIndex?: number) => string;
 
 export type ColorProcessor<SeriesType extends ChartSeriesType> = (
   series: DefaultizedSeriesType<SeriesType>,
diff --git a/packages/x-charts/src/internals/resolveColorProcessor.test.ts b/packages/x-charts/src/internals/resolveColorProcessor.test.ts
diff --git a/packages/x-charts/src/internals/resolveColorProcessor.ts b/packages/x-charts/src/internals/resolveColorProcessor.ts
diff --git a/packages/x-charts/src/models/colorMapping.ts b/packages/x-charts/src/models/colorMapping.ts

Original file line number	Diff line number	Diff line change
`@@ -14,9 +14,9 @@ const getColor: ColorProcessor<'rangeBar'> = (series, xAxis, yAxis) => {`
`14`	`14`	`}`
`15`	`15`
`16`	`16`	`const value = bandValues[dataIndex];`
`17`		`- const color = value === null ? getSeriesColor({ value, dataIndex }) : bandColorScale(value);`
	`17`	`+ const color = bandColorScale(value);`
`18`	`18`
`19`		`- if (color === null) {`
	`19`	`+ if (typeof color !== 'string') {`
`20`	`20`	`return getSeriesColor({ value, dataIndex });`
`21`	`21`	`}`
`22`	`22`
Original file line number	Diff line number	Diff line change
`@@ -20,11 +20,8 @@ const getColor: ColorProcessor<'scatter'> = (series, xAxis, yAxis, zAxis) => {`
`20`	`20`	`}`
`21`	`21`	`}`
`22`	`22`	`const value = series.data[dataIndex];`
`23`		`- const color =`
`24`		`- value === null`
`25`		`- ? getSeriesColor({ value, dataIndex })`
`26`		`- : zColorScale(value.colorValue ?? value.z);`
`27`		`- if (color === null) {`
	`23`	`+ const color = zColorScale(value.colorValue ?? value.z);`
	`24`	`+ if (typeof color !== 'string') {`
`28`	`25`	`return getSeriesColor({ value, dataIndex });`
`29`	`26`	`}`
`30`	`27`	`return color;`
`@@ -37,8 +34,8 @@ const getColor: ColorProcessor<'scatter'> = (series, xAxis, yAxis, zAxis) => {`
`37`	`34`	`return series.color;`
`38`	`35`	`}`
`39`	`36`	`const value = series.data[dataIndex];`
`40`		`- const color = value === null ? getSeriesColor({ value, dataIndex }) : yColorScale(value.y);`
`41`		`- if (color === null) {`
	`37`	`+ const color = yColorScale(value.y);`
	`38`	`+ if (typeof color !== 'string') {`
`42`	`39`	`return getSeriesColor({ value, dataIndex });`
`43`	`40`	`}`
`44`	`41`	`return color;`
`@@ -51,8 +48,8 @@ const getColor: ColorProcessor<'scatter'> = (series, xAxis, yAxis, zAxis) => {`
`51`	`48`	`return series.color;`
`52`	`49`	`}`
`53`	`50`	`const value = series.data[dataIndex];`
`54`		`- const color = value === null ? getSeriesColor({ value, dataIndex }) : xColorScale(value.x);`
`55`		`- if (color === null) {`
	`51`	`+ const color = xColorScale(value.x);`
	`52`	`+ if (typeof color !== 'string') {`
`56`	`53`	`return getSeriesColor({ value, dataIndex });`
`57`	`54`	`}`
`58`	`55`	`return color;`
Original file line number	Diff line number	Diff line change
`@@ -14,10 +14,12 @@ export function getSequentialColorScale<Value extends number \| Date>(`
`14`	`14`	`config: ContinuousColorConfig<Value> \| PiecewiseColorConfig<Value>,`
`15`	`15`	`) {`
`16`	`16`	`if (config.type === 'piecewise') {`
`17`		`- return scaleThreshold(config.thresholds, config.colors);`
	`17`	`+ return scaleThreshold(config.thresholds, config.colors).unknown(config.unknownColor ?? null);`
`18`	`18`	`}`
`19`	`19`
`20`		`- return scaleSequential([config.min ?? 0, config.max ?? 100], config.color);`
	`20`	`+ return scaleSequential([config.min ?? 0, config.max ?? 100], config.color).unknown(`
	`21`	`+ config.unknownColor ?? null,`
	`22`	`+ );`
`21`	`23`	`}`
`22`	`24`
`23`	`25`	`export function getOrdinalColorScale<Value extends number \| Date \| string>(`