Skip to main content

Use charts to display data visualizations in UI extensions. HubSpot provides two chart components: BarChart and LineChart. 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.

Learn more about creating custom charts with UI extensions by watching this video on the HubSpot Developers YouTube channel.

On this page:

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.
  • axes: an object that specifies for the x and y axes, with additional options. Learn more about configuring axes.
  • options: an object that specifies options for the chart, such as showing data labels and tooltips. Learn more about chart options.

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.

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.

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)

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.

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.

ParameterTypeDescription
fieldRequiredStringThe name of the field from the dataset.
fieldTypeRequiredStringThe type of data in the field. You can specify one of the following types:
  • category: data that can be bucketed into categories or types, such as different types of products.
  • datetime: date and time data. Charts support the following datetime formats:
    • JavaScript timestamp (1758791725)
    • ISO 8601 timestamp (2025-09-25T09:15:25+0000)
    • ISO 8601 date (2024-09-25)
  • linear: numerical data, such as quantity. One of the axes must have this fieldType.
labelStringThe label to display on the axis. If not specified, the field value will be used instead.
optionsObjectAdditional configuration options for the axes:
  • groupFieldByColor (string): specify a field to group by color. When not specified, only one color will be used for data visualization.
  • stacking (boolean): when set to true, grouped data will be stacked. Default is false.

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 via the groupFieldByColor parameter in options.

simple-bar-chart-example-sales

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

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

Compare the above visualization to the version below without stacking:

line-chart-no-stacking-comparison

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

ParameterTypeDescription
titleStringThe title of the chart.
showTooltipsBooleanWhen set to true, displays tooltips for data points on hover. Default is false.
showLegendBooleanWhen set to true, displays a legend above the table to help users understand the data. Default is false.
showDataLabelsBooleanWhen set to true, displays labels above data points for readability. Default is false.
colorListArrayAn array of strings specifying the order that colors should be used in the chart. Learn more about 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

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

Below are the available colors in their default order.

ColorHex valueSwatch
orange#fea58enull
aqua#51d3d9null
purple#bda9eanull
yellow#f5c78enull
pink#ea90b1null
blue#81c1fdnull
green#a4d398null
darkOrange#c3705cnull
darkAqua#009ca2null
darkPurple#8775b2null
darkYellow#bb915bnull
darkPink#b05c7dnull
darkBlue#468cc4null
darkGreen#6b9a5bnull
  • 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.