diff --git a/docs/data/charts/gauge/BasicGauges.js b/docs/data/charts/gauge/BasicGauges.js new file mode 100644 index 000000000000..d5eb57bbf55b --- /dev/null +++ b/docs/data/charts/gauge/BasicGauges.js @@ -0,0 +1,11 @@ +import * as React from 'react'; +import { Gauge } from '@mui/x-charts/Gauge'; + +export default function BasicGauges() { + return ( + + + + + ); +} diff --git a/docs/data/charts/gauge/BasicGauges.tsx b/docs/data/charts/gauge/BasicGauges.tsx new file mode 100644 index 000000000000..d5eb57bbf55b --- /dev/null +++ b/docs/data/charts/gauge/BasicGauges.tsx @@ -0,0 +1,11 @@ +import * as React from 'react'; +import { Gauge } from '@mui/x-charts/Gauge'; + +export default function BasicGauges() { + return ( + + + + + ); +} diff --git a/docs/data/charts/gauge/BasicGauges.tsx.preview b/docs/data/charts/gauge/BasicGauges.tsx.preview new file mode 100644 index 000000000000..c1c453a70983 --- /dev/null +++ b/docs/data/charts/gauge/BasicGauges.tsx.preview @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/docs/data/charts/gauge/GaugeValueRangeNoSnap.js b/docs/data/charts/gauge/GaugeValueRangeNoSnap.js new file mode 100644 index 000000000000..bd1bf64864b5 --- /dev/null +++ b/docs/data/charts/gauge/GaugeValueRangeNoSnap.js @@ -0,0 +1,11 @@ +import * as React from 'react'; +import { Gauge } from '@mui/x-charts/Gauge'; + +export default function GaugeValueRangeNoSnap() { + return ( + + + + + ); +} diff --git a/docs/data/charts/gauge/GaugeValueRangeNoSnap.tsx b/docs/data/charts/gauge/GaugeValueRangeNoSnap.tsx new file mode 100644 index 000000000000..bd1bf64864b5 --- /dev/null +++ b/docs/data/charts/gauge/GaugeValueRangeNoSnap.tsx @@ -0,0 +1,11 @@ +import * as React from 'react'; +import { Gauge } from '@mui/x-charts/Gauge'; + +export default function GaugeValueRangeNoSnap() { + return ( + + + + + ); +} diff --git a/docs/data/charts/gauge/GaugeValueRangeNoSnap.tsx.preview b/docs/data/charts/gauge/GaugeValueRangeNoSnap.tsx.preview new file mode 100644 index 000000000000..bbe7d47d9345 --- /dev/null +++ b/docs/data/charts/gauge/GaugeValueRangeNoSnap.tsx.preview @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/docs/data/charts/gauge/PlaygroundNoSnap.js b/docs/data/charts/gauge/PlaygroundNoSnap.js new file mode 100644 index 000000000000..6dbfaa251eb4 --- /dev/null +++ b/docs/data/charts/gauge/PlaygroundNoSnap.js @@ -0,0 +1,85 @@ +import * as React from 'react'; +import ChartsUsageDemo from 'docsx/src/modules/components/ChartsUsageDemo'; +import Paper from '@mui/material/Paper'; +import { Gauge } from '@mui/x-charts/Gauge'; + +export default function PlaygroundNoSnap() { + return ( + ( + + + + )} + getCode={({ props }) => { + const { innerRadius, outerRadius, ...numberProps } = props; + return [ + `import { Gauge } from '@mui/x-charts/Gauge';`, + '', + ` ` ${name}={${value}}`, + ), + ...Object.entries({ innerRadius, outerRadius }).map( + ([name, value]) => ` ${name}="${value}%"`, + ), + '/>', + ].join('\n'); + }} + /> + ); +} diff --git a/docs/data/charts/gauge/gauge.md b/docs/data/charts/gauge/gauge.md index ffa248998caf..1b25806aa50d 100644 --- a/docs/data/charts/gauge/gauge.md +++ b/docs/data/charts/gauge/gauge.md @@ -1,15 +1,69 @@ --- title: React Gauge chart productId: x-charts +components: Gauge, GaugeContainer +waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/meter/ --- -# Charts - Gauge 🚧 +# Charts - Gauge

Gauge charts let the user evaluate metrics.

-:::warning -The Gauge Chart component isn't available yet, but you can upvote [**this GitHub issue**](https://github.com/mui/mui-x/issues/2903) to see it arrive sooner. +## Basic gauge -Don't hesitate to leave a comment there to influence what gets built. -Especially if you already have a use case for this component, or if you're facing a pain point with your current solution. +The Gauge display a numeric value that varies within a defined range. + +{{"demo": "BasicGauges.js"}} + +## Value range + +The value of the Gauge is provided by props `value`. + +By default it's assumed to be between 0 and 100. +You can modify this range with props `valueMin` and `valueMax`. + +{{"demo": "GaugeValueRangeNoSnap.js"}} + +## Arcs configuration + +You can modify the arc shape with the following props: + +- `startAngle`, `endAngle`: Angle range provided in degrees +- `innerRadius`, `outerRadius`: Radius of the arc. It can be a number for fix number of px. Or a percentage string which will be a percent of the maximal available radius. +- `cornerRadius`: It can be a number for fix number of px. Or a percentage string which will be a percent of distance between inner and outer radius. + +{{"demo": "PlaygroundNoSnap.js"}} + +:::info +Notice that the arc position is computed to let the Gauge take as much space as possible in the drawing area. + +Provide props `cx` and/or `cy` to fix the coordinate of the arc center. ::: + +## Accessibility + +(WAI-ARIA: [https://www.w3.org/WAI/ARIA/apg/patterns/meter/](https://www.w3.org/WAI/ARIA/apg/patterns/meter/)) + +### Label + +If a visible label is available, reference it by adding `aria-labelledby` attribute. +Otherwise, the label can be provided by `aria-label`. + +### Presentation + +Assistive technologies often present the value as a percentage. +This can be modified by providing `aria-valuetext` attribute. + +For example a battery level indicator is better with a duration in hours. + +```jsx +

+ Battery level +

+ +```