You can use the Chart Config Editor to customize formatting options on Looker visualizations that use the HighCharts API. This includes most Cartesian charts, such as the column chart, bar chart, and line chart, among others.
Prerequisites
To access the Chart Config Editor, you must have the can_override_vis_config
permission.
Customizing a visualization
To customize a visualization with the Chart Config Editor, follow these steps:
- View a visualization in an Explore, or edit a visualization in a Look or dashboard.
- Open the Edit menu in the visualization.
Click the Edit Chart Config button in the Plot tab. Looker displays the Edit Chart Config dialog.
The Chart Config (Source) pane contains the original JSON of your visualization and cannot be edited.
The Chart Config (Override) pane contains the JSON that should override the source JSON. When you first open the Edit Chart Config dialog, Looker populates the pane with some default JSON. You can start with this JSON, or you can delete this JSON and enter any valid HighCharts JSON.
Select the Chart Config (Override) section and enter some valid HighCharts JSON. The new values will override any values in the Chart Config (Source) section.
- See the Examples section of this article for examples of valid HighCharts JSON.
- Looker accepts any valid JSON values. Looker does not accept functions, dates, or undefined values.
Click <> (Format code) to allow Looker to properly format your JSON.
Click Preview to test your changes.
Click Apply to apply your changes. The visualization will be displayed using the custom JSON values.
Once you've customized your visualization, you can save the visualization. If you viewed the visualization in an explore, save the Explore. If you edited a Look or a dashboard, click Save.
If you try to preview code containing invalid JSON, Looker will display an Invalid JSON detected
error message . You can clean up invalid JSON using the Autofix code option at the bottom of the Chart Config (Override) pane.
If you'd like edit the default visualization options, first remove any changes you've made in the Chart Config Editor, then replace them later. Specifically, follow these steps:
- Click the Edit Chart Config button in the Plot tab. Looker displays the Edit Chart Config dialog.
- Copy the text in the Chart Config (Override) pane.
- Click the Clear Chart Overrides button to delete all changes.
- Click Apply.
- Edit your visualization using the default visualization options.
- Click the Edit Chart Config button in the Plot tab. Looker displays the Edit Chart Config dialog.
- Enter some valid HighCharts JSON in the Chart Config (Override) pane. You can use the text that you copied in step 2 as a template, but be sure to test your changes using the Preview button to ensure there are no conflicts.
- Click Apply.
Conditional formatting with series formatters
The Chart Config Editor accepts most valid HighCharts JSON. It also accepts the series formatters
attribute, which only exists in Looker. Each series can have multiple formatters to combine different style rules.
The series formatters
attribute accepts two attributes: select
and style
.
- Enter a logical expression in the
select
attribute to indicate which data values will be formatted. - Enter some JSON into the
style
attribute to indicate how to format the data values.
For example, the following JSON will color each data value orange if it is greater than or equal to 380:
{
series: [{
formatters: [{
select: 'value >= 380',
style: {
color: 'orange'
}
}]
}]
}
The following sections describe the potential values of the select
and style
attributes in more detail.
The select
attribute
You can use the following values in a select
expression:
value
: This variable returns the value of the series. For example, you could useselect: value > 0
to target all positive values, orvalue = 100
to only match series with a value of 100.max
: Useselect: max
to target the series value that has the maximum value.min
: Useselect: min
to target the series value that has the minimum value.percent_rank
: This variable targets the series value with a specified percentile. For example, you could useselect: percent_rank >= 0.9
to target series values in the ninetieth percentile.name
: This variable returns the dimension value of the series. For example, if you had a chart showing Sold, Canceled, and Returned orders, you could useselect: name = Sold
to target the series where the dimension value is Sold.AND/OR
UseAND
andOR
to combine multiple logical expressions.
To see these expressions implemented in the Chart Config Editor, refer to the Color the maximum, minimum, and percentile values example.
The style
attribute
The style
attribute can be used to apply styles that HighCharts supports. For example, you can color series values using style.color
, color series borders using style.borderColor
, and set series border width using style.borderWidth
. For a more complete list of style options, see the Highcharts options for series.column.data
.
For line visualizations, use style.marker.fillColor
and style.marker.lineColor
instead of style.color
. For a more complete list of line style options, see the Highcharts options for series.line.data.marker
.
To see color formatting implemented in the Chart Config Editor, refer to the Color the maximum, minimum, and percentile values example.
Examples
The following sections provide examples of some common use cases for the Chart Config Editor. For a complete list of the attributes that you can edit, see the HighCharts API documentation.
- Change the background color and axis text color
- Customize tooltip color
- Add chart annotations and captions
- Add vertical reference bands
- Color the maximum, minimum, and percentile values
Change the background color and axis text color
To change the background color of a visualization, use the chart.backgroundColor
attribute.
Similarly, to change the text color of the axes in a visualization, use the following attributes:
The following HighCharts JSON changes the background color of the visualization to purple, and the text of the axis titles and labels to white.
{
chart: {
backgroundColor: "purple"
},
xAxis: {
labels: {
style: {
color: "white"
}
},
title: {
style: {
color: "white"
}
}
},
yAxis: {
labels: {
style: {
color: "white"
}
},
title: {
style: {
color: "white"
}
}
}
}
Customize tooltip color
To customize the color of the tooltip, use the following attributes:
The following HighCharts JSON changes the background color of the tooltip to cyan, and changes the color of the tooltip text to black.
{
tooltip: {
backgroundColor: "cyan",
style: {
color: "black"
}
}
}
Customize tooltip content and styles
To customize the content of the tooltip, use the following attributes:
The following HighCharts JSON changes the tooltip format such that the x-axis value appears at the top of the tooltip in larger font, followed by a list of all series values at that point.
This example uses the following HighCharts functions and variables:
{key}
is a variable that returns the x-axis value of the selected point. (in this example, the month and year).{#each points}{/each}
is a function that repeats the enclosed code for each series in the chart.{series.name}
is a variable that returns the name of the series.{y:.2f}
is a variable that returns the y-axis value of the selected point, rounded to two decimal places.{y}
is a variable that returns the y-axis value of the selected point.{variable:.2f}
roundsvariable
to two decimal places. See the Highcharts templating documentation for more examples of value formatting.
{
tooltip: {
format: '<span style="font-size: 1.8em">{key}</span><br/>{#each points}<span style="color:{color}; font-weight: bold;">\u25CF {series.name}: </span>{y:.2f}<br/>{/each}',
shared: true
},
}
Add chart annotations and captions
To add an annotation, use the annotations
attribute. To add a caption to the chart, use the caption
attribute.
To get the coordinates for a point, click Inspect Point Metadata at the top of the Edit Chart Config dialog. Then, hold the pointer over the data point that you'd like to annotate. Looker displays a point ID, which you can use in the annotations.labels.point
attribute.
The following HighCharts JSON adds two annotations to the chart to explain a decrease in inventory items after certain periods of time. It also adds a caption to the bottom of the chart to explain the annotations in more detail.
{
caption: {
text: 'Items go on clearance after 60 days, and are thrown away after 80 days. Thus we see large drops in inventory after these events.'
},
annotations: [{
labels: [{
point: "inventory_items.count-60-79",
text: "Clearance sale"
},
{
point: "inventory_items.count-80+",
text: "Thrown away"
},
]
}]
}
Add vertical reference bands
To add a vertical reference band, use the xAxis.plotBands
attribute.
The following HighCharts JSON adds a vertical reference band between November 24, 2022 and November 29, 2022 to denote a sale period. It also adds a caption to the bottom of the chart to explain the significance of the band.
Note that the to
and from
attributes of xAxis.plotBands
must correspond to data values in the chart. In this example, since the data is time-based, the attributes accept Unix timestamp values (1669680000000 for November 29, 2022 and 1669248000000 for November 24, 2022). String-based date formats like MM/DD/YYYY and DD-MM-YY are not supported in the to
and from
HighCharts attributes.
{
caption: {
text: 'This chart uses the HighCharts plotBands attribute to display a band around the Black Friday Cyber Monday sale period.'
},
xAxis: {
plotBands: [{
to: 1669680000000,
from: 1669248000000,
label: {
text: 'BFCM Sale Period'
}
}]
},
}
Add dotted and dashed lines
To change solid lines to dotted or dashed lines, use the series.dashStyle
attribute.
The following HighCharts JSON changes the dashStyle
attribute of the Customers
series to a dashed line, and the dashStyle
attribute of the Sales
series to a dotted line.
{
series: [{
name: 'Customers',
dashStyle: 'Dash'
}, {
name: 'Sales',
dashStyle: 'Dot'
}]
}
Color the maximum, minimum, and percentile values
See the Getting the most out of Looker visualizations cookbook: Conditional formatting customization in Cartesian charts page for an in-depth example about coloring the maximum, minimum, and percentile values of a Cartesian visualization.
Creating new visualization types
You can use the Chart Config Editor to create visualization types that aren't included in Looker's default visualization types. The following articles provide examples of some of the visualizations that you can design with the Chart Config Editor:
- Creating a bullet chart with the Chart Config Editor
- Creating a solid gauge chart with the Chart Config Editor
- Creating a streamgraph chart with the Chart Config Editor
- Creating a treemap chart with the Chart Config Editor
- Creating a Sankey chart with the Chart Config Editor
- Creating a Venn diagram with the Chart Config Editor
- Creating a sunburst chart with the Chart Config Editor