> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

---
id: e2eeb131-0b96-42aa-b4e8-6c9af53b4b64
---

# BarChart | UI components

> Learn about the BarChart component for use in UI extensions.

The `BarChart` component renders a bar chart for visualizing data. This type of chart is best suited for comparing categorical data. Alternatively, you can use a [LineChart](/apps/developer-platform/add-features/ui-extensions/ui-components/standard-components/charts/line-chart) component for time series plots or visualizing trend data. Learn more about [charts](/apps/developer-platform/add-features/ui-extensions/ui-components/standard-components/charts/overview).

To see an example of how to implement charts in a UI extension, check out [HubSpot's Charts example project](https://github.com/HubSpot/ui-extensions-examples/tree/main/charts-example). Note that this is a version `2025.1` project, but the chart component implementation would be similar for projects on version `2025.2` or `2026.03`.

<Frame>
  <img src="https://www.hubspot.com/hubfs/Knowledge_Base_2023_2024/bar-chart-diagram-labels-2.png" alt="bar-chart-diagram-labels-2" />
</Frame>

1. **Title:** the title of the chart.
2. **Legend:** lists the data categories with their corresponding color for readability.
3. **Axis label:** the label for the axis.
4. **Data labels:** labels for data points.

```jsx theme={null}
import { BarChart } from '@hubspot/ui-extensions';

const dailyInventorySample = [
    {
      Product: 'Hats',
      Amount: 187,
    },
    {
      Product: 'Socks',
      Amount: 65,
    },
    {
      Product: 'Ascots',
      Amount: 120,
    }
  ];
  return (
    <BarChart
      data={dailyInventorySample}
      axes={{
        x: { field: 'Product', fieldType: 'category' },
        y: { field: 'Amount', fieldType: 'linear' },
        options: {groupFieldByColor: 'Product'}
      }}
      options={{
        title: "My chart",
        showLegend: true,
        showDataLabels: true,
        showTooltips: true
      }}
    />
  );
};
```

## Props

| Parameter | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`    | Object | An object containing the chart's data in an array. <ul><li>Data should be formatted as comma-separated objects containing key-value pairs.</li><li>Data will be displayed in the order it's provided, so any sorting will need to be done before passing it to the component.</li><li>While it's recommended to pre-format your data to be human-readable, you can also provide the `propertyLabels` parameter via this prop's `options` to relabel data values. See example in the [Stacking section](#stacking) below.</li></ul>Learn more about [formatting data](/apps/developer-platform/add-features/ui-extensions/ui-components/standard-components/charts/overview#formatting-data).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `axes`    | Object | Configures the chart's axes. Using the `x` and `y` fields, you'll configure each axis individually with `field` and `fieldType` parameters, along with an optional `label` parameter:<ul><li>`field` (Required): the field from your dataset to use. This value will be used as the displayed axis label if no `label` is specified.</li><li>`fieldType` (Required): the type of field. Can be `category`, `datetime`, or `linear`. Learn more about [field types](/apps/developer-platform/add-features/ui-extensions/ui-components/standard-components/charts/overview#configuring-axes).</li><li>`label`: the axis label. If not specified, the `field` value will be used.</li></ul>You can also include an `options` field to further configure the axes with the following options:<ul><li>`groupFieldByColor` (string): specify a field to [apply color](#colors) to for visual clarity.[](#color-grouping)</li><li>`stacking` (boolean): [stack grouped data](#stacking) instead of always rendering separate bars.</li><li>`colors` (object): [specify colors for values](#specify-colors-per-field-value) in the field specified in `groupFieldByColor`.</li></ul>Learn more about [chart axes](/apps/developer-platform/add-features/ui-extensions/ui-components/standard-components/charts/overview#configuring-axes). |
| `options` | Object | Additional chart configuration options. Options include:<ul><li>`title` (string): a title for the chart.</li><li>`showLegend` (boolean): set to `true` to display a legend above the chart. </li><li>`showDataLabels` (boolean): set to `true` to display labels above data points.</li><li>`showTooltips` (boolean): set to `true` to display tooltips for data points on hover.</li><li>`colorList` (array): specify a custom order for colors to used in the report.</li></ul>Learn more about [chart options](/apps/developer-platform/add-features/ui-extensions/ui-components/standard-components/charts/overview#chart-options).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

## Colors

To apply colors to a chart for visual clarity, you can group data fields by color using the `groupFieldByColor` parameter within the axes `options`. For example, the bar chart below use `groupFieldByColor` to add colors to each `Product` defined in the dataset.

<Frame>
  <img src="https://www.hubspot.com/hubfs/Knowledge_Base_2023_2024/Screenshot%202024-09-30%20at%2010.38.53%20AM.png" alt="Screenshot 2024-09-30 at 10.38.53 AM" />
</Frame>

```jsx theme={null}
const dailyInventorySample = [
  {
    Product: "Standalone product A",
    Sales: 159,
  },
  {
    Product: "Bundle A",
    Sales: 53,
  },
  {
    Product: "Bundle B",
    Sales: 99,
  },
];
return (
  <BarChart
    data={dailyInventorySample}
    axes={{
      x: { field: "Product", fieldType: "category" },
      y: { field: "Sales", fieldType: "linear" },
      options: { groupFieldByColor: "Product" },
    }}
  />
);
```

For comparison, below is the same chart without `groupFieldByColor` configured for the axes:

<Frame>
  <img src="https://www.hubspot.com/hubfs/Knowledge_Base_2023_2024/Screenshot%202024-09-30%20at%2010.42.11%20AM.png" alt="Screenshot 2024-09-30 at 10.42.11 AM" />
</Frame>

Colors will be automatically assigned in a [preset order](/apps/developer-platform/add-features/ui-extensions/ui-components/standard-components/charts/overview#colors). To customize the color selection order, include the `colorList` field in the `options` prop, then specify the colors to pick from as shown below.

<Frame>
  <img src="https://www.hubspot.com/hubfs/Knowledge_Base_2023_2024/bar-charts-with-colorlist.png" alt="bar-charts-with-colorlist" />
</Frame>

```jsx theme={null}
const dailyInventorySample = [
  {
    Product: "Standalone product A",
    Sales: 159,
  },
  {
    Product: "Bundle A",
    Sales: 53,
  },
  {
    Product: "Bundle B",
    Sales: 99,
  },
];
return (
  <BarChart
    data={dailyInventorySample}
    axes={{
      x: { field: "Product", fieldType: "category" },
      y: { field: "Sales", fieldType: "linear" },
      options: { groupFieldByColor: "Product" },
    }}
    options={{
      colorList: ["purple", "green", "darkBlue"],
    }}
  />
);
```

Or you can specify colors to use for specific values in the field specified in `groupFieldByColor`. To do so, include the `colors` field within the axes `options`, then specify each field value and color, as shown below. Learn more about [colors](/apps/developer-platform/add-features/ui-extensions/ui-components/standard-components/charts/overview#colors).

<Frame>
  <img src="https://www.hubspot.com/hubfs/Knowledge_Base_2023_2024/bar-chart-with-field-specific-colors.png" alt="bar-chart-with-field-specific-colors" />
</Frame>

```jsx theme={null}
const dailyInventorySample = [
  {
    Product: "Standalone product A",
    Sales: 159,
  },
  {
    Product: "Bundle A",
    Sales: 53,
  },
  {
    Product: "Bundle B",
    Sales: 99,
  },
];
return (
  <BarChart
    data={dailyInventorySample}
    axes={{
      x: { field: "Product", fieldType: "category" },
      y: { field: "Sales", fieldType: "linear" },
      options: {
        groupFieldByColor: "Product",
        colors: {
          "Standalone product A": "blue",
          "Bundle A": "orange",
          "Bundle B": "yellow",
        },
      },
    }}
  />
);
```

## Stacking

Use the stacking axes option to stack grouped data rather than rendering individual bars. For example, the following bar chart displays the number of deals by deal stage. The data also includes the sales rep who owns each deal. Because two sales reps have deals in the same deal stage, `stacking` has been set to `true` to visually combine the data into one bar.

<Frame>
  <img src="https://www.hubspot.com/hubfs/Knowledge_Base_2023_2024/bar-chart-stacked-data.png" alt="bar-chart-stacked-data" />
</Frame>

```jsx theme={null}
const Extension = ({ context }) => {
  const dealCountSample = [
    {
      count: 1,
      dealstage: "appointmentScheduled",
      user_id: "194784",
    },
    {
      count: 2,
      dealstage: "closedWon",
      user_id: "295834",
    },
    {
      count: 1,
      dealstage: "closedWon",
      user_id: "938453",
    },
  ];

  return (
    <BarChart
      data={{
        data: dealCountSample,
        options: {
          propertyLabels: {
            dealstage: {
              appointmentScheduled: "Appointments scheduled (Sales)",
              closedWon: "Closed won (Sales)",
            },
            user_id: {
              194784: "Sales user A",
              295834: "Sales user B",
              938453: "Sales user C",
            },
          },
        },
      }}
      axes={{
        x: {
          field: "dealstage",
          fieldType: "category",
          label: "Deal Stage",
        },
        y: {
          field: "count",
          fieldType: "linear",
          label: "Count of Deals",
        },
        options: { groupFieldByColor: "user_id", stacking: true },
      }}
      options={{
        showLegend: true,
        showDataLabels: true,
        showTooltips: true,
      }}
    />
  );
};
```

<Info>
  Because the `dealstage` field data is not written in a human-readable format (e.g., `appointmentScheduled`), the data prop includes `propertyLabels` in its `options` to convert the labels. Note that the data prop formatting is slightly different to accommodate both the dataset and its `options`. Learn more about [data options](/apps/developer-platform/add-features/ui-extensions/ui-components/standard-components/charts/overview#data-options).
</Info>

For comparison, below is the same chart without stacking. In this version, each sales rep has their own bar in the deal stage category.

<Frame>
  <img src="https://www.hubspot.com/hubfs/Knowledge_Base_2023_2024/bar-chart-no-stacking-comparison.png" alt="bar-chart-no-stacking-comparison" />
</Frame>

## Guidelines

* **DO:** title your data categories with human-readable text so they are easy to understand.
* **DO:** use sentence-casing for the data categories and chart title (only first letter capitalized).
* **DO:** sort your data in ascending/descending order of your x-axis field to prevent unordered rendering prior to passing it to a charting component. If you intend to display information over time, your data will be displayed in the order you provide it.
* **DO:** display the chart legend if you’re graphing more than one category of data. This prevents your users from having to rely only on color to identify different data on your chart.
* **DO:** for readability, use larger surfaces to showcase charts, such as the record page middle column. Avoid using charts with many data points on smaller surfaces such as the preview panel or sidebar.
* **DON’T:** use more than 14 data categories unless it cannot be avoided for your use case.
* **DON’T:** use the same colors to indicate different data categories.

## Related components

* [BarChart](/apps/developer-platform/add-features/ui-extensions/ui-components/standard-components/charts/bar-chart)
* [Statistics](/apps/developer-platform/add-features/ui-extensions/ui-components/standard-components/statistics)
* [Table](/apps/developer-platform/add-features/ui-extensions/ui-components/standard-components/table)