The LineChart
component renders a line chart for visualizing data. This type of chart is best suited for time series plots or trend data. Alternatively, you can use a BarChart component for comparing categorical data. Learn more about charts.
To see an example of how to implement charts in a UI extension, check out HubSpot's Charts example project.
- Title: the title of the chart.
- Legend: lists the data categories with their corresponding color for readability.
- Axis label: the label for the axis.
- Data labels: labels for data points.
import { LineChart } from '@hubspot/ui-extensions';
const salesOverTimeSample = [
{
Date: '2024-08-01',
Sales: 10,
},
{
Date: '2024-08-02',
Sales: 30,
},
{
Date: '2024-08-03',
Sales: 60,
},
];
return (
<LineChart
data={salesOverTimeSample}
axes={{
x: { field: 'Date', fieldType: 'datetime' },
y: { field: 'Sales', fieldType: 'linear' },
}}
options={{
title: 'My chart',
showLegend: true,
showDataLabels: true,
showTooltips: true,
}}
/>
);
Parameter | Type | Description |
---|---|---|
data Required | Object | An object containing the chart's data in an array.
|
axes Required | 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:
options field to further configure the axes with the following options:
|
options | Object | Additional chart configuration options. Options include:
|
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 line chart below use groupFieldByColor
to add colors to each Breakdown
category defined in the dataset.
xxxxxxxxxx
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 (
<LineChart
data={VisitsPerSourceOverTime}
axes={{
x: { field: 'Session Date', fieldType: 'category' },
y: { field: 'Visits', fieldType: 'linear' },
options: { groupFieldByColor: 'Breakdown' },
}}
options={{ showLegend: true }}
/>
);
Colors will be automatically assigned in a preset order. To customize the color selection order, include the colorList
field in the options
prop, then specify the colors to pick from as shown below.
xxxxxxxxxx
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 (
<LineChart
data={VisitsPerSourceOverTime}
axes={{
x: { field: 'Session Date', fieldType: 'category' },
y: { field: 'Visits', fieldType: 'linear' },
options: { groupFieldByColor: 'Breakdown' },
}}
options={{
showLegend: true,
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.
xxxxxxxxxx
return (
<LineChart
data={VisitsPerSourceOverTime}
axes={{
x: { field: 'Session Date', fieldType: 'category' },
y: { field: 'Visits', fieldType: 'linear' },
options: {
groupFieldByColor: 'Breakdown',
colors: {
Direct: 'blue',
Email: 'orange',
Referrals: 'yellow',
},
},
}}
options={{ showLegend: true }}
/>
);
Use the stacking
axes option to stack grouped data for visual comparison. For example, the following line chart displays website visits over time broken down by source. To help users compare data within each breakdown category, stacking
has been set to true
.
xxxxxxxxxx
const visitsPerSourceOverTime = [
{
sessionDate: '2019-09-01',
breakdown: 'direct',
visits: 1277,
},
{
sessionDate: '2019-09-01',
breakdown: 'referrals',
visits: 1882,
},
{
sessionDate: '2019-09-01',
breakdown: 'email',
visits: 1448,
},
{
sessionDate: '2019-09-02',
breakdown: 'direct',
visits: 1299,
},
{
sessionDate: '2019-09-02',
breakdown: 'referrals',
visits: 1869,
},
{
sessionDate: '2019-09-02',
breakdown: 'email',
visits: 1408,
},
{
sessionDate: '2019-09-03',
breakdown: 'direct',
visits: 1357,
},
{
sessionDate: '2019-09-03',
breakdown: 'referrals',
visits: 1931,
},
{
sessionDate: '2019-09-03',
breakdown: 'email',
visits: 1391,
},
];
return (
<LineChart
data={{
data: visitsPerSourceOverTime,
options: {
propertyLabels: {
breakdown: {
direct: 'Direct',
email: 'Email',
referrals: 'Referrals',
},
},
},
}}
axes={{
x: { field: 'sessionDate', fieldType: 'category', label: 'Session Date' },
y: { field: 'visits', fieldType: 'linear', label: 'Visits' },
options: { groupFieldByColor: 'breakdown', stacking: true },
}}
options={{ showLegend: true }}
/>
);
Because the breakdown
field data is all lowercase (e.g., direct
), 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.
- 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.