# MeterChart component for Stripe Apps

A meter chart displays a whole divided into segments, each representing a proportion of the total.

# v9


To add the `MeterChart` component to your app:

```js
import {MeterChart} from '@stripe/ui-extension-sdk/ui';
```

`MeterChart` displays a total as a set of segments, where each segment represents a proportion of that total. Use it to visualize how a value is distributed across categories. The `data` prop accepts multiple data formats that determine how the object displays each segment of the chart. Each data point needs to include the fields required to render the chart correctly, such as `label` and `value`.

## Props

### MeterChart props

| Property         | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`           | (Required)
  `({     label: string;     value: number; } & {     [x: string]: unknown; })[]`

  Plain points data which is used in charts.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `legendEnabled`  | (Optional)
  `boolean | undefined`

  If this attribute is true, it renders the legend component.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `onSegmentClick` | (Optional)
  `((payload: MeterChartSegmentClickPayload) => void) | undefined`

  Called when a meter segment or legend item is clicked.

  Related types: [MeterChartSegmentClickPayload](https://docs.stripe.com/stripe-apps/components/meterchart.md#meterchartsegmentclickpayload).                                                                                                                                                                                                                                                                                            |
| `unitFormat`     | (Optional)
  `(CurrencyUnitFormat | PercentUnitFormat | NumberUnitFormat | NoneUnitFormat) | undefined`

  The unit formatting to use for values.

  Related types: [CurrencyUnitFormat](https://docs.stripe.com/stripe-apps/components/meterchart.md#currencyunitformat), [NoneUnitFormat](https://docs.stripe.com/stripe-apps/components/meterchart.md#noneunitformat), [NumberUnitFormat](https://docs.stripe.com/stripe-apps/components/meterchart.md#numberunitformat), [PercentUnitFormat](https://docs.stripe.com/stripe-apps/components/meterchart.md#percentunitformat). |

### MeterChartSegmentClickPayload

| Property    | Type                                                                                              |
| ----------- | ------------------------------------------------------------------------------------------------- |
| `data`      | (Required)
  `({     label: string;     value: number; } & {     [x: string]: unknown; }) | null` |
| `eventType` | (Required)
  `"meter.segment.click" | "meter.legend.click"`                                       |

### CurrencyUnitFormat

| Property  | Type                                                                                                                                         |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `options` | (Required)
  `Options`

  Related types: [Options](https://docs.stripe.com/stripe-apps/components/meterchart.md#currencyunitformat-options). |
| `unit`    | (Required)
  `"currency"`                                                                                                                    |

### CurrencyUnitFormat Options

| Property   | Type                                                      |
| ---------- | --------------------------------------------------------- |
| `currency` | (Required)
  `string`

  3 letter ISO-4217 currency code. |

### PercentUnitFormat

| Property  | Type                                                                                                                                        |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `options` | (Required)
  `Options`

  Related types: [Options](https://docs.stripe.com/stripe-apps/components/meterchart.md#percentunitformat-options). |
| `unit`    | (Required)
  `"percent"`                                                                                                                    |

### PercentUnitFormat Options

| Property      | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `signDisplay` | (Optional)
  `("always" | "auto" | "never" | "exceptZero") | undefined` |

### NumberUnitFormat

| Property  | Type                                                                                                                                       |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `options` | (Required)
  `Options`

  Related types: [Options](https://docs.stripe.com/stripe-apps/components/meterchart.md#numberunitformat-options). |
| `unit`    | (Required)
  `"number"`                                                                                                                    |

This component has no props.

### NoneUnitFormat

| Property | Type                  |
| -------- | --------------------- |
| `unit`   | (Required)
  `"none"` |

## Next version

### Unit format

Control how values are displayed in the chart legend. Refer to the `unitFormat` [prop](https://docs.stripe.com/stripe-apps/components/meterchart.md#meterchart-props) description for available options.

### Click events

Customize the `onSegmentClick` callback to track clicks on either a chart segment or a legend item.


## See also

- [Design patterns to follow](https://docs.stripe.com/stripe-apps/patterns.md)
- [Style your app](https://docs.stripe.com/stripe-apps/style.md)
- [UI testing](https://docs.stripe.com/stripe-apps/ui-testing.md)