> ## 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: d319cb0c-cdf1-4614-88b2-2b9e2d942e33 --- # Charts overview | UI components > Learn about the available chart components for visualizing data in UI extensions. Use charts to display data visualizations in UI extensions. HubSpot provides two chart components: [BarChart](/apps/developer-platform/add-features/ui-extensions/ui-components/standard-components/charts/bar-chart) and [LineChart](/apps/developer-platform/add-features/ui-extensions/ui-components/standard-components/charts/line-chart). Both components use the same API, but the each type is better suited for different types of data. For example, a bar chart is generally recommended for comparing categorical data, while a line chart is recommended for time series plots or visualizing trends. To see an example of how to implement charts in a UI extension, check out [HubSpot's Charts example projects](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`. Learn more about creating custom charts with UI extensions by watching [this video](https://www.youtube.com/watch?v=5P6WuKyOiDE) on the HubSpot Developers YouTube channel. On this page: * [Formatting data](#formatting-data) * [Configuring axes](#configuring-axes) * [Stacking](#stacking) * [Chart options](#chart-options) * [Colors](#colors) * [Design guidelines](#design-guidelines) ```js theme={null} import { BarChart, LineChart } from "@hubspot/ui-extensions"; ``` For both types of charts, there are three main props: * `data`: an object containing the chart data, with additional `options`. Learn more about [data formatting](#formatting-data). * `axes`: an object that specifies for the `x` and `y` axes, with additional `options`. Learn more about [configuring axes](#configuring-axes). * `options`: an object that specifies options for the chart, such as showing data labels and tooltips. Learn more about [chart options](#chart-options). ## Formatting data Data should be provided to a chart component in an array of objects containing key-value pairs, matching the following format `{string: number | string}`. Data will be displayed in the order it's provided to the component, so you will need to sort data beforehand if necessary. For example, to display data over time in a `LineChart`, you should sort the data in ascending/descending order of your `datetime` axis field before passing it to the chart component. ```jsx theme={null} [ { type: "referral", count: 35, location: "location_A", }, { type: "direct", count: 12, location: "location_B", }, ]; ``` When building out a chart, keep the following in mind: * A chart can only graph one dataset, so you'll need multiple charts if you're working with multiple datasets. * For performance and readability, it's recommended for a chart to include no more than a few hundred entries, depending on the data. When working with larger datasets, it's important to consider the information you want to convey with the chart. You'll likely encounter issues with visual clarity before you encounter performance issues. For example, a `BarChart` with hundreds of bars on it will likely not be readable even if it renders quickly. * Chart components do not support nested fields in data. Rather, all fields will need to be stored at the same level. For example, the following data format is not supported because it introduces a secondary level of data in the `type` field. ```jsx theme={null} [ { type: { value: "referral", subType: "subtypeValue", }, count: 35, location: "location_A", }, ]; ``` ### datetime values For charts that include datetime data, you can use the following formats: * Unix millisecond timestamp (`1758791725`) * ISO 8601 timestamp (`2025-09-25T09:15:25+0000`) * ISO 8601 date (`2024-09-25`) ### Data options It's recommended to pre-format your data into human-readable text so that it doesn't need any additional relabeling. However, if there are times when you can't pre-format certain values in your data, you can include an `options` field in the `data` prop to set `propertyLabels`. Including `options` will slightly change the way you format `data`: * When only including a dataset array, you'll format the `data` prop as `data={dataArray}`. * When including `options`, you'll need to format the `data` prop as an object containing both `data` and `options` fields as shown below. In `options`, you'll include a `propertyLabels` object, which then contains an object for each field and labels for each value. For example, the following chart is configured to relabel the `dealstage` and `user_id` values. ```jsx theme={null} ); ``` ## Configuring axes The `axes` prop configures the chart's axes. Charts can have two axes (`x` and `y`), and each axis is configured by a `field` and `fieldType` parameter. By default, the `field` value will be used as the axis label, but you can also include a `label` parameter to set it separately. **Please note:** One axis must have a `fieldType` of `linear`. ```jsx theme={null} ; ``` | Parameter | Type | Description | | ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `field` | String | The name of the field from the dataset. | | `fieldType` | String | The type of data in the field. You can specify one of the following types: | | `label` | String | The label to display on the axis. If not specified, the `field` value will be used instead. | | `options` | Object | Additional configuration options for the axes: | The following bar chart displays sales data by type of product and count of sales. To add visual clarity, each bar is assigned a different [color](#colors) via the `groupFieldByColor` parameter in `options`. simple-bar-chart-example-sales ```jsx theme={null} const dailyInventorySample = [ { Product: "Hats", Amount: 187, }, { Product: "Socks", Amount: 65, }, { Product: "Ascots", Amount: 120, }, ]; return ( ); ``` ### Stacking Use the `stacking` axes option to stack data by group. 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. To visually distinguish sales reps in each column, `stacking` has been set to `true`. bar-chart-stacked-data ```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 ( ); }; ``` Compare the above visualization to the version below without stacking: bar-chart-no-stacking-comparison Similarly, you can use stacking in line charts, as shown in the example chart below. This chart measures website visits by date, broken down by source. Stacking in this example helps to emphasize volume over time. line-chart-stacked-data ```jsx theme={null} const visitsPerSourceOverTime = [ { "Session Date": "2019-09-01", Breakdown: "Direct", Visits: 1277, }, { "Session Date": "2019-09-01", Breakdown: "Referrals", Visits: 1882, }, { "Session Date": "2019-09-01", Breakdown: "Email", Visits: 1448, }, { "Session Date": "2019-09-02", Breakdown: "Direct", Visits: 1299, }, { "Session Date": "2019-09-02", Breakdown: "Referrals", Visits: 1869, }, { "Session Date": "2019-09-02", Breakdown: "Email", Visits: 1408, }, { "Session Date": "2019-09-03", Breakdown: "Direct", Visits: 1357, }, { "Session Date": "2019-09-03", Breakdown: "Referrals", Visits: 1931, }, { "Session Date": "2019-09-03", Breakdown: "Email", Visits: 1391, }, ]; return ( ); ``` Compare the above visualization to the version below without stacking: line-chart-no-stacking-comparison ## Chart options Using the `options` prop, you can configure a chart with options such as displaying a chart title, legend, data labels, or specifying the color list. numbered-chart-options-diagram 1. **Title:** the title of the chart. 2. **Legend:** lists the data categories with their corresponding color for readability. 3. **Data labels:** labels for data points. 4. **Tooltips:** displays details for data points on hover. barchart-component-with-tooltip ```jsx theme={null} ; ``` | Parameter | Type | Description | | ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------- | | `title` | String | The title of the chart. | | `showTooltips` | Boolean | When set to `true`, displays tooltips for data points on hover. Default is `false`. | | `showLegend` | Boolean | When set to `true`, displays a legend above the table to help users understand the data. Default is `false`. | | `showDataLabels` | Boolean | When set to `true`, displays labels above data points for readability. Default is `false`. | | `colorList` | Array | An array of strings specifying the order that colors should be used in the chart. Learn more about [colors](#colors). | ## Colors By default, HubSpot will apply colors to chart bars or lines using a default set of colors when `groupFieldByColor` is specified in axes `options`. You can customize these colors in two ways: * To customize the order of colors selected by HubSpot, include the `colorList` field in the top-level `options` prop, then specify the colors you want to prioritize. * To apply colors to specific values of the field specified in `groupFieldByColor`, include the `colors` field within the axes `options`. For example, the chart below is configured to apply colors to data in the `Product` field using `groupFieldByColor`. The three colors (`darkGreen`, `blue`, `darkPurple`) will be applied first, then the standard color order will be applied to any additional bars. bar-chart-color-configurations_2 ```jsx theme={null} const dailyInventorySample = [ { Product: "Standalone product A", Sales: 159, }, { Product: "Bundle A", Sales: 53, }, { Product: "Bundle B", Sales: 99, }, ]; return ( ); ``` If instead you want to manually apply colors to specific field values, rather than have HubSpot assign colors in order, you could instead include the `colors` field in the axes `options`. In colors, you'll need to specify each value from the `groupFieldByColor` field to assign a color to. bar-chart-with-field-specific-colors ```jsx theme={null} const dailyInventorySample = [ { Product: "Standalone product A", Sales: 159, }, { Product: "Bundle A", Sales: 53, }, { Product: "Bundle B", Sales: 99, }, ]; return ( ); ``` ### Default color set Below are the available colors in their default order. | Color | Hex value | Swatch | | ------------ | --------- | --------------------------------------------------------------------------------------------------------------- | | `orange` | #fea58e | null | | `aqua` | #51d3d9 | null | | `purple` | #bda9ea | null | | `yellow` | #f5c78e | null | | `pink` | #ea90b1 | null | | `blue` | #81c1fd | null | | `green` | #a4d398 | null | | `darkOrange` | #c3705c | null | | `darkAqua` | #009ca2 | null | | `darkPurple` | #8775b2 | null | | `darkYellow` | #bb915b | null | | `darkPink` | #b05c7d | null | | `darkBlue` | #468cc4 | null | | `darkGreen` | #6b9a5b | null | ## Design 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 (such as in a LineChart), 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.