You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A gauge shows a numeric value within a defined range, often as an arc or needle against a scale.
19
+
Use it for metrics like progress, capacity, or levels (for example, battery, storage, or completion).
17
20
18
-
The Gauge displays a numeric value that varies within a defined range.
21
+
The demo below shows basic gauge configurations.
19
22
20
23
{{"demo": "BasicGauges.js"}}
21
24
22
-
## Value range
25
+
## Basics
23
26
24
-
The Gauge's value is provided through the `value` props, which accept a value range between 0 and 100.
25
-
To modify it, use the `valueMin` and `valueMax` props.
27
+
Pass the current value with the `value` prop.
28
+
By default, the scale runs from 0 through 100.
29
+
Use `valueMin` and `valueMax` to set a different range.
26
30
27
31
{{"demo": "GaugeValueRange.js"}}
28
32
29
-
## Arcs configuration
33
+
## Arc configuration
30
34
31
-
Modify the arc shape with the following props:
35
+
Use these props to change the arc shape:
32
36
33
-
-`startAngle` and `endAngle`: The angle range provided in degrees
34
-
-`innerRadius` and `outerRadius`: The arc's radii. It can be a fixed number of pixels or a percentage string, which will be a percent of the maximal available radius
35
-
-`cornerRadius`: It can be a fixed number of pixels or a percentage string, which will be a percent of the maximal available radius
37
+
-`startAngle` and `endAngle`: angle range in degrees
38
+
-`innerRadius` and `outerRadius`: arc radii, as a pixel value or a percentage string (such as `'50%'`)
39
+
-`cornerRadius`: corner rounding, as a pixel value or percentage string
To customize the Gauge styles, use the `gaugeClasses` export to pull class names from different parts of the component, such as `valueText`, `valueArc`, and `referenceArc`.
62
+
Use the `gaugeClasses` export for class names that target different parts of the gauge, such as `valueText`, `valueArc`, and `referenceArc`.
60
63
61
-
For a full reference list, visit the [API page](/x/api/charts/gauge/#classes).
64
+
See [Gauge—Classes](/x/api/charts/gauge/#classes) for the full list.
62
65
63
66
{{"demo": "ArcDesign.js"}}
64
67
65
68
## Adding elements
66
69
67
70
### Using the default Gauge
68
71
69
-
To insert more elements into the Gauge, the first option would be to add them as children, which means they will be stacked on top of the default rendering.
72
+
Add elements as children of `Gauge`to render them on top of the default arc and text.
70
73
71
74
```tsx
72
75
import { Gauge } from'@mui/x-charts/Gauge';
@@ -78,11 +81,11 @@ import { Gauge } from '@mui/x-charts/Gauge';
78
81
79
82
### Using the Gauge container
80
83
81
-
The second option is to make use of the following elements that are available within the Gauge module:
84
+
Use `GaugeContainer` and the following components when you need more control over the layout:
82
85
83
-
-Gauge Reference Arc
84
-
-Gauge Value Arc
85
-
-Gauge Value Text
86
+
-`GaugeReferenceArc`: the reference arc
87
+
-`GaugeValueArc`: the value arc
88
+
-`GaugeValueText`: the text in the center
86
89
87
90
```tsx
88
91
import {
@@ -99,33 +102,33 @@ import {
99
102
</GaugeContainer>;
100
103
```
101
104
102
-
### Creating your components
105
+
### Creating custom components
103
106
104
-
To create your own components, use the `useGaugeState()` hook which provides all you need about the gauge configuration:
107
+
Use the `useGaugeState()` hook to build custom gauge components.
108
+
It returns:
105
109
106
-
- information about the value: `value`, `valueMin`, `valueMax`
107
-
- information to plot the arc: `startAngle`, `endAngle`, `outerRadius`, `innerRadius`, `cornerRadius`, `cx`, and `cy`
108
-
- computed values:
109
-
-`maxRadius`: the maximal radius that can fit the drawing area
110
-
-`valueAngle`: the angle associated with the current value
- Computed: `maxRadius` (largest radius that fits the drawing area) and `valueAngle` (angle for the current value)
111
113
112
114
{{"demo": "CompositionExample.js"}}
113
115
114
116
## Accessibility
115
117
116
-
The MUI X Gauge is compliant with the [Meter ARIA pattern](https://www.w3.org/WAI/ARIA/apg/patterns/meter/), which includes the addition of the `meter` role to the parent container and correct usage of the `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` attributes.
118
+
The gauge follows the [Meter ARIA pattern](https://www.w3.org/WAI/ARIA/apg/patterns/meter/).
119
+
The container has the `meter` role, and `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` match the value range.
117
120
118
121
### Label
119
122
120
-
If a visible label is available, reference it by adding `aria-labelledby`attribute.
121
-
Otherwise, the label can be manually provided by`aria-label`.
123
+
If the gauge has a visible label, set `aria-labelledby`to point to it.
124
+
Otherwise, provide a label with`aria-label`.
122
125
123
126
### Presentation
124
127
125
128
Assistive technologies often present the value as a percentage.
126
-
This can be modified by providing`aria-valuetext` attribute.
129
+
You can override this by setting the`aria-valuetext` attribute.
127
130
128
-
For example, a battery level indicator is better with an hour-long duration.
131
+
For example, a battery level indicator is clearer when it announces a duration (such as hours remaining) instead of only a percentage.
129
132
130
133
```jsx
131
134
<h3 id="battery_level_label">
@@ -141,15 +144,15 @@ For example, a battery level indicator is better with an hour-long duration.
141
144
142
145
## Composition
143
146
144
-
Use the `<GaugeContainer />` to provide all the parameters as props: `value`, `valueMin`, `valueMax`, `startAngle`, `endAngle`, etc.
147
+
Use `GaugeContainer` to supply the gauge parameters: `value`, `valueMin`, `valueMax`, `startAngle`, `endAngle`, and so on.
145
148
146
-
In addition to the common chart components available for [composition](/x/react-charts/composition/), you can use the following components:
149
+
In addition to the shared chart components available for [composition](/x/react-charts/composition/), you can use:
147
150
148
-
-`<GaugeReferenceArc />` renders the reference arc.
149
-
-`<GaugeValueArc />` renders the value arc.
150
-
-`<GaugeValueText />` renders the text at the center.
<pclass="description">Heatmap charts visually represents data with color variations to highlight patterns and trends across two dimensions.</p>
9
+
<pclass="description">Use heatmap charts to show intensity as a grid of colored cells across two dimensions.</p>
10
10
11
11
## Overview
12
12
13
-
Heatmaps are ideal for visualizing intensity variations across two categorical or continuous dimensions. They highlight areas of high and low concentration in a dataset, making it easy to detect trends, clusters, or anomalies at a glance. Each cell in a heatmap represents the intersection of two variables, with color encoding used to convey the magnitude of a numerical value.
13
+
A heatmap shows how a numeric value varies across two dimensions as a grid of colored cells.
14
+
Each cell is the intersection of an x and y category or tick, and color encodes the value.
15
+
16
+
Use heatmaps to spot areas of higher or lower intensity, clusters, or anomalies.
17
+
18
+
The demo below shows bicycle counts in Paris by day and hour.
Heatmap charts series must contain a `data` property containing an array of 3-tuples.
19
-
The first two numbers in each tuple correspond to the x and y indexes of the cell, respectively.
20
-
The third number is the value for the given cell.
24
+
A heatmap series must include a `data` property with an array of 3-tuples.
25
+
Each tuple is `[xIndex, yIndex, value]`.
26
+
The first two numbers are the cell's x and y indices, and the third is the cell value.
21
27
22
28
```jsx
23
29
<Heatmap
@@ -32,92 +38,94 @@ The third number is the value for the given cell.
32
38
/>
33
39
```
34
40
35
-
You can specify x and y ticks with the `xAxis` and `yAxis` props.
41
+
Use the `xAxis` and `yAxis` props to set x and y ticks.
36
42
37
43
{{"demo": "BasicHeatmap.js"}}
38
44
39
45
## Color mapping
40
46
41
-
To customize the color mapping, use the `zAxis` configuration.
42
-
You can either use the piecewise or continuous [color mapping](https://mui.com/x/react-charts/styling/#value-based-colors).
47
+
Use the `zAxis` configuration to customize how values map to color.
48
+
You can use piecewise or continuous scales.
49
+
See [Styling—Value-based colors](/x/react-charts/styling/#value-based-colors) for details.
43
50
44
51
{{"demo": "ColorConfig.js"}}
45
52
46
53
## Highlight
47
54
48
-
You can choose to highlight the hovered element by setting `highlightScope.highlight` to `'item'`.
49
-
To fade the other item, set `highlightScope.fade` to `'global'`.
55
+
Set `highlightScope.highlight` to `'item'` to highlight the hovered cell.
56
+
Set `highlightScope.fade` to `'global'` to fade the other cells.
50
57
51
58
{{"demo": "HighlightHeatmap.js"}}
52
59
53
-
By default highlighted/faded effect is obtained by applying the CSS property `filter: saturate(...)`to cells.
54
-
To modify this styling, use the `heatmapClasses.highlighted` and `heatmapClasses.faded`CSS classes to override the applied style.
60
+
By default, the highlight and fade use the CSS `filter: saturate(...)`property.
61
+
You can override the effect with the `heatmapClasses.highlighted` and `heatmapClasses.faded` classes.
55
62
56
-
In the following demo, we replace the highlight saturation by a border radius and reduce the saturation of the faded cells.
63
+
The demo below uses border radius on the highlighted cell and reduced saturation for faded cells.
57
64
58
65
{{"demo": "HighlightClasses.js"}}
59
66
60
-
## Click event
67
+
## Click events
61
68
62
-
Use `onItemClick` to know which cell is clicked by user.
69
+
Use `onItemClick` to handle cell clicks.
63
70
64
-
The first argument is the click event.
65
-
The second one is the item identifier.
66
-
It contains the properties `xIndex` and `yIndex` that are the indexes of the clicked cell along the x- and y-axes respectively.
67
-
68
-
If this cell has associated data, the `dataIndex` property indicates the position of the cell's data within the series' `data` array.
71
+
The handler receives the click event as the first argument and an item object as the second.
72
+
The item includes `xIndex` and `yIndex` (cell position on the x- and y-axes) and, when the cell has data, `dataIndex` (index in the series `data` array).
69
73
70
74
{{"demo": "HeatmapCellClick.js"}}
71
75
72
-
## Common features
76
+
## Shared features
73
77
74
-
The heatmap shares several features with other charts.
75
-
This section only explains the details that are specific to the heatmap.
76
-
If you'd like to learn more about the shared features, you can visit their dedicated pages.
78
+
Heatmap charts use the same axis, tooltip, and legend patterns as other charts.
79
+
This section notes heatmap-specific details.
80
+
See the linked pages for full options.
77
81
78
82
### Axes
79
83
80
-
The Heatmap axes can be customized like any other chart axis.
81
-
The available options are available in the [axis customization page](/x/react-charts/axis/#axis-customization).
84
+
You can configure heatmap axes like other chart axes.
85
+
See [Axis—Customization](/x/react-charts/axis/#axis-customization) for details.
82
86
83
87
### Tooltip
84
88
85
-
The Heatmap has an item tooltip that can be customized as described in the [Tooltip documentation page](/x/react-charts/tooltip/).
89
+
The default heatmap tooltip is item-based.
90
+
You can customize it with slots.
91
+
See [Tooltip](/x/react-charts/tooltip/) for details.
86
92
87
-
The only difference of the Heatmap Tooltip is its default content.
88
-
You can import the default tooltip, or only its content as follows:
93
+
The heatmap package exports the default tooltip and its content if you want to reuse or extend them:
0 commit comments