QuickChart Documentation
QuickChart is a web service that generates chart images on-the-fly. These images are suitable for embedding in email, SMS, chatbots, and other formats. Charts are rendered by Chart.js, a popular open-source charting library.
Do you have questions? Don't hesitate to ask in our community or send us a message.
QuickChart works by taking Chart.js configurations and rendering them on the backend as an image. You may send your chart configuration in JSON or Javascript format using a simple URL or through POST request.
For example, take this simple Chart.js configuration:
{
type: 'bar', // Show a bar chart
data: {
labels: [2012, 2013, 2014, 2015, 2016], // Set X-axis labels
datasets: [{
label: 'Users', // Create the 'Users' dataset
data: [120, 60, 50, 180, 120] // Add data to the chart
}]
}
}
We'll pack this Chart.js object into the /chart
endpoint URL:
The URL generates this chart image, a rendering of the Chart.js config above:
Make adjustments to this example - try editing the chart and replacing "bar" with "line" or "pie" to get different types of chart, change the legend labels, or add another dataset to get a grouped bar chart.
Because QuickChart is built on open-source chart libraries, our charts are flexible and highly customizable. Explore the documentation below to learn more or view more examples.
The chart endpoint https://quickchart.io/chart
accepts these query parameters:
chart
: Javascript/JSON definition of the chart. Use a Chart.js configuration object. Abbreviated as "c"
Please URL-encode your chart configuration. If not encoded, you may run into problems with special characters or syntax errors in your program. You may also use base64 encoding (see encoding
option).
width=500
: Width of the image. Abbreviated as "w"height=300
: Height of the image. Abbreviated as "h"devicePixelRatio=2.0
: Device pixel ratio of the output (defaults to retina=2.0). Width and height are multiplied by this value.backgroundColor=transparent
: Background of the chart canvas. Accepts rgb (rgb(255,255,120)
), colors (red
), and URL-encoded hex values (%23ff00ff
). Abbreviated as "bkg"format=png
: Format of your output. Supported output formats are PNG, WebP, SVG, and PDF. Abbreviated as "f"encoding=url
: Encoding of your "chart" parameter. Accepted values are url
and base64
.version=2.9.4
: Chart.js version. Defaults to latest 2.x.x. Setting version
to 3
enables latest stable Chart.js v3 support (see documentation). Abbreviated as "v"
Combine these parameters in your query string. For example: /chart?width=500&height=300&format=pdf&c={...}
. Numerous client libraries are available so you do not need to construct the URL yourself, if you prefer.
To test requests with Postman,
Errors that prevent the chart from rendering will return a non-200 HTTP status code, most commonly `400 Bad Request`. In most cases, the error will be rendered in the requested image format. If an error is rendered in an image, it is also included as a string in the X-quickchart-error
HTTP header.
An example error due to invalid chart config - not URL encoded.
Invalid or unexpected token: Invalid Chart.js configurations may return errors similar to this one. The most common cause of this error is that the caller forgot to URL-encode the chart
variable. The next most common cause is invalid JSON/Javascript syntax in the chart configuration.
Cannot read property <X> of undefined and <X> is not a function: Access to certain Chart.js internals, used especially in plugins, is restricted due to potential for abuse. Contact us to get whitelisted for these features.
If your chart is large or complicated, you may prefer to send a POST request rather than a GET request. This avoids limitations on URL length and means you don't have to worry about URL encoding. The /chart
POST endpoint returns a chart. It takes the standard request parameters as a JSON object:
{
"backgroundColor": "transparent",
"width": 500,
"height": 300,
"format": "png",
"chart": {...},
}
Note that if you want to include Javascript code in chart
(e.g. to format labels), you'll have to send the entire chart
parameter as a string rather than a JSON object. For examples, see documentation on using JS Functions.
You may want to create a shorter URL for your charts, especially if you are sending them via email or SMS. To generate a short URL for your chart, send a POST request to https://quickchart.io/chart/create
per the above POST spec.
Here's an example using curl. You can use any library that sends an HTTP POST request:
curl -X POST \
-H 'Content-Type: application/json' \
-d '{"chart": {"type": "bar", "data": {"labels": ["Hello", "World"], "datasets": [{"label": "Foo", "data": [1, 2]}]}}}' \
https://quickchart.io/chart/create
Here's an equivalent request using Python:
import json
import requests
quickchart_url = 'https://quickchart.io/chart/create'
post_data = {'chart': {'type': 'bar', 'data': {'labels': ['Hello', 'World'],
'datasets': [{'label': 'Foo', 'data': [1, 2]}]}}}
response = requests.post(
quickchart_url,
json=post_data,
)
if (response.status_code != 200):
print('Error:', response.text)
else:
chart_response = json.loads(response.text)
print(chart_response)
You will get a response that looks like this:
{
"success": true,
"url": "https://quickchart.io/chart/render/9a560ba4-ab71-4d1e-89ea-ce4741e9d232"
}
Go to the URL in the response to render your chart.
Please note the following limitations:
If you want to generate many charts, but they only differ slightly, you may prefer to use chart templates. Any chart with a Short URL can also be used as a template.
Customize a template by adding URL parameters to the template URL. The following template parameters are supported:
For example, this URL will take template zf-abc-123
and update its title to "New title":
https://quickchart.io/chart/render/zf-abc-123?title=New title
We can add a labels URL parameter:
https://quickchart.io/chart/render/zf-abc-123?title=New title&labels=Q1,Q2,Q3,Q4
Or even override multiple datasets:
https://quickchart.io/chart/render/zf-abc-123?data1=40,60,80,100&data2=5,6,7,8
In addition to plain numbers, templates also accept (x, y) data values and arbitrary JSON objects.
An example walkthrough with a live template can be viewed here.
If you prefer not to edit a Chart.js configuration directly, use the Chart Maker to create a chart without code. Design a chart, save it as a template, easily customize it using a few URL parameters, andembed it anywhere.
To learn more about no-code chart APIs and templates, see the chart maker documentation.
Use the no-code chart builder to generate a customized chart API.
You can use the QuickChart web service by building a standard URL, so a client library is not a requirement. However, we've released several optional client libraries for your convenience:
Run npm install quickchart-js
to install the QuickChart dependency. Use it like so:
const QuickChart = require('quickchart-js');
const myChart = new QuickChart();
myChart
.setConfig({
type: 'bar',
data: { labels: ['Hello world', 'Foo bar'], datasets: [{ label: 'Foo', data: [1, 2] }] },
})
.setWidth(800)
.setHeight(400)
.setBackgroundColor('transparent');
// Print the chart URL
console.log(myChart.getUrl());
Get more details on the quickchart-js project page.
Run pip install quickchart.io
to install the QuickChart dependency. Use it like so:
from quickchart import QuickChart
qc = QuickChart()
qc.width = 500
qc.height = 300
qc.device_pixel_ratio = 2.0
qc.config = {
"type": "bar",
"data": {
"labels": ["Hello world", "Test"],
"datasets": [{
"label": "Foo",
"data": [1, 2]
}]
}
}
# Print the chart URL
print(qc.get_url())
Read the full Python tutorial or see details on the quickchart-python project page.
Run gem install quickchart
to install the QuickChart Ruby gem:
require 'quickchart'
qc = QuickChart.new(
{
type: "bar",
data: {
labels: ["Hello world", "Test"],
datasets: [{
label: "Foo",
data: [1, 2]
}]
}
},
width: 600,
height: 300,
device_pixel_ratio: 2.0,
)
# Print the chart URL
puts qc.get_url
Learn more about chart generation in Ruby at the quickchart-ruby repository.
Run composer require ianw/quickchart
to install the QuickChart PHP library:
require 'quickchart'
$qc = new QuickChart(array(
'width' => 600,
'height' => 300,
));
$qc->setConfig('{
type: "bar",
data: {
labels: ["Hello world", "Test"],
datasets: [{
label: "Foo",
data: [1, 2]
}]
}
}');
// Print the chart URL
echo $qc->getUrl();
See the PHP QuickChart client at the quickchart-php repository.
Add the QuickChart package from NuGet. Then use the Chart
object provided by the QuickChart
namespace:
namespace QuickChartExample
{
public class SimpleExample
{
static void Main(string[] args) {
Chart qc = new Chart();
qc.Width = 500;
qc.Height = 300;
qc.Config = @"{
type: 'bar',
data: {
labels: ['Hello world', 'Test'],
datasets: [{
label: 'Foo',
data: [1, 2]
}]
}
}"
Console.WriteLine(qc.GetUrl());
}
}
}
The C# QuickChart client is available on NuGet and at the quickchart-csharp repository.
Add the QuickChart package from Maven Central. If you use Maven or Gradle, you can add it to your config (view details).
This library provides an io.quickchart
package that contains a QuickChart
class:
import io.quickchart.QuickChart;
public class PrintUrlExample {
public static void main(String[] args) {
QuickChart chart = new QuickChart();
chart.setWidth(500);
chart.setHeight(300);
chart.setConfig("{"
+ " type: 'bar',"
+ " data: {"
+ " labels: ['Q1', 'Q2', 'Q3', 'Q4'],"
+ " datasets: [{"
+ " label: 'Users',"
+ " data: [50, 60, 70, 180]"
+ " }]"
+ " }"
+ "}"
);
System.out.println(chart.getUrl());
}
}
The Java library is open-source and accessible on Github.
A third-party Go library is available on Github. It can be used like so:
qc := quickchartgo.New()
qc.Config = chartConfig
qc.Config := `{
type: 'bar',
data: {
labels: ['Q1', 'Q2', 'Q3', 'Q4'],
datasets: [{
label: 'Users',
data: [50, 60, 70, 180]
}]
}
}`
qc.Width = 500;
qc.Height = 300;
qc.Version = "2.9.4";
fmt.Println(qc.GetUrl());
QuickChart is not limited to the listed libraries. You can create a QuickChart URL in any language by building a URL string. Because building a URL string is a matter of string concatenation, this can be done in any language.
See the API Parameters documentation to learn how to build a URL that renders a chart image. If you need help, please reach out and we will help you implement in your preferred programming language.
We've created dozens of examples of different charts that you can edit interactively:
For a variety of useful editable examples, see the chart gallery.
Customization can be very simple. By changing type: bar
to type: line
, for example, we can instantly produce an equivalent line graph:
<img src="https://quickchart.io/chart?c={type:'bar',data:{labels:['January','February', 'March','April', 'May'], datasets:[{label:'Dogs',data:[50,60,70,180,190]},{label:'Cats',data:[100,200,300,400,500]}]}}">
Set type
to horizontalBar
for a horizontal bar chart. Bar Chart documentation
<img src="https://quickchart.io/chart?c={type:'line',data:{labels:['January','February', 'March','April', 'May'], datasets:[{label:'Dogs', data: [50,60,70,180,190], fill:false,borderColor:'blue'},{label:'Cats', data:[100,200,300,400,500], fill:false,borderColor:'green'}]}}">
There are many other chart types as well:
<img src="https://quickchart.io/chart?c={type:'radar',data:{labels:['January','February', 'March','April', 'May'], datasets:[{label:'Dogs',data:[50,60,70,180,190]},{label:'Cats',data:[100,200,300,400,500]}]}}">
<img src="https://quickchart.io/chart?c={type:'pie',data:{labels:['January','February', 'March','April', 'May'], datasets:[{data:[50,60,70,180,190]}]}}">
Pie Chart documentation. You can also use options for the Chart.js datalabels plugin.
Learn how to customize pie chart labels.
<img src="https://quickchart.io/chart?c={type:'doughnut',data:{labels:['January','February','March','April','May'],datasets:[{data:[50,60,70,180,190]}]},options:{plugins:{doughnutlabel:{labels:[{text:'550',font:{size:20}},{text:'total'}]}}}}">
Doughnut Chart documentation. You can also use options from the Chart.js doughnutlabel plugin.
Learn how to customize doughnut chart labels.
<img src="https://quickchart.io/chart?c={type:'polarArea',data:{labels:['January','February', 'March','April', 'May'], datasets:[{data:[50,60,70,180,190]}]}}">
Polar charts are like pie and doughnut charts, except each segment has the same angle and the radius of the segments varies based on the value. Polar Area Chart documentation
<img src="https://quickchart.io/chart?c={type:'scatter',data:{datasets:[{label:'Data 1',data:[{x:2,y:4},{x:3,y:3},{x:-10,y:0},{x:0,y:10},{x:10,y:5}]}]}}">
<img src="https://quickchart.io/chart?c={type:'bubble',data:{datasets:[{label:'Data 1',data:[{x:1,y:4,r:9},{x:2,y:4,r:6},{x:3,y:8,r:30},{x:0,y:10,r:1},{x:10,y:5,r:5}]}]}}">
Bubble is similar to Scatter except that the r
variable defines bubble radius in pixels.
Bubble Chart documentation
<img src="https://quickchart.io/chart?c={type:'radialGauge',data:{datasets:[{data:[70],backgroundColor:'green'}]}}">
View the options at chartjs-radial-gauge for customization details.
<img src="https://quickchart.io/chart?c={type:'violin', data:{labels:[2012,2013,2014,2015], datasets:[{label:'Data',data:[[12,6,3,4], [1,8,8,15],[1,1,1,2,3,5,9,8], [19,-3,18,8,5,9,9]], backgroundColor:'rgba(56,123,45,0.2)', borderColor:'rgba(56,123,45,1.9)'}]}}">
You can use violin
, boxplot
, horizontalBoxPlot
, and horizontalViolin
chart types. View the options at chartjs-chart-box-and-violin-plot for customization details. For best results, add it with a scatter plot!
<img src="https://quickchart.io/chart?c={type:'sparkline',data:{datasets:[{data:[140,60,274,370,199]}]}}">
A sparkline is a special case of line graph with axes and other labeling removed. All line graph options can be applied. Read more about the sparkline API.
<img src="https://quickchart.io/chart?c={type:'progressBar',data:{datasets:[{data:[50]}]}}">
A progress bar is a special case of a horizontal bar chart with axes and other labeling removed. All bar options can be applied.
The first dataset specifies the number shown. By default, this number is a percentage and the total value is 100. If your data is not out of 100, add a second dataset to override the total.
You can combine charts together by specifying different "types":
<img src="https://quickchart.io/chart?c={type:'bar',data:{labels:['January','February', 'March','April', 'May'], datasets:[{label:'Dogs',data:[50,60,70,180,190]},{label:'Cats',data:[100,200,300,400,500],},{type:'line',fill:false, label:'Potatoes',data:[100,400,200,400,700]}]}}">
This web service supports QR code generation. You may render a QR code like so:
https://quickchart.io/qr?text=Here's my text
Remember the URL-encode your text
parameter for more complex strings. The QR endpoint produces a PNG image by default. You may optionally set the query parameter format=svg
for SVG format.
Specify the whitespace around QR image in modules with query parameter margin
(defaults to 4), size
determines the pixel dimensions of the image (defaults to 150), and error correction level with ecLevel=M
(valid values: L, M, Q, H).
If you'd like to customize the color of your QR code, use dark=000000
and light=ffffff
. The parameters must be hex color codes. Here's the same code as above but with slimmer margins, more error protection, and colors:
https://quickchart.io/qr?text=Here's%20my%20text&dark=f00
Use our interactive QR code generator to preview API behavior and test things out. You may also be interested in how to generate QR codes in a spreadsheet.
Customize your chart title by providing an options.title object.
You may specify a list of strings to show a multi-line title or subtitle. You may also set position, fontSize, fontFamily, fontColor, padding, and other attributes. See full Chart.js title documentation for more.
The example below sets options.title.display to true and options.title.text to "Basic chart title" in order to show a title at the top of the chart.
Chart gridlines are customizable by setting attributes on options.scales.<xAxes/yAxes>.gridLines. This configuration is very flexible. For example, you can change the color, size, and style of gridlines (e.g. making them dotted or dashed). See full Gridlines documentation for more.
The example below removes gridlines by setting gridLines.display to false.
There are several types of chart axes: Linear, Logarithmic, Time, Categorical, and Radial. If you are looking to create a standard chart, chances are you want to use a linear or time axis.
Axes are configured in the options.scales object. Learn more about chart axes, including attributes to customize those axes, here. Because a wide variety of customizations are possible, we've prepared a number of examples. Head over to the gallery to see some examples of custom axes and scales.
To set the range of chart values, use axis.ticks.min and axis.ticks.max. Use axis.ticks.stepSize to control the increment of each tick mark. For more information, see Chart.js ticks.
This example sets the start value to 0 and the end value to 100, with tick marks every 20:
{
// ...
options: {
yAxes: [{
ticks: {
min: 0,
max: 100,
stepSize: 20
}
}]
}
}
You can use the axis object to create a stacked bar chart by setting stacked to true on each axis. Read more here.
The example below includes a stacked bar chart.
It is possible to create two or more X or Y axes by providing multiple objects in the options.scales.xAxes or options.scales.yAxes lists. For each axis, set display to true and give it an id. Each dataset should reference this id as yAxisID or xAxisID. See below for an example.
There are several different types of labels: axis labels, tick labels, and data labels.
Axis labels can be set using the axis.scaleLabel property. Here's an example config:
// ...
options: {
scales: {
xAxes: [
{
scaleLabel: {
display: true,
labelString: 'Month',
}
}
]
yAxes: [
{
scaleLabel: {
display: true,
labelString: '# Users',
fontColor: '#ff0000',
fontSize: 20,
fontStyle: 'bold',
}
}
]
}
}
Learn more about scale title configuration here.
X axis tick labels come from the "labels" property on the data.datasets object. This example chart uses the labels
attribute to control the X axis display.
Y axis tick labels are automatically generated based on values unless you are using a categorical axis.
"Ticks" are the data markings that run along the axis. To format tick label, use the options.scales.<xAxes/yAxes>.ticks property. There are many ways to customize tick values - learn more about configuring ticks.
Attribute Name | Description |
---|---|
min |
Minimum value for the scale |
max |
Maximum value for the scale |
suggestedMin |
Soft minimum value for the scale. The chart will use this minimum by default, but the minimum will be overridden if data value is less than suggested value. |
suggestedMax |
Soft maximum value for the scale. The chart will use this maximum by default, but the maximum will be overridden if data value is greater than suggested value. |
callback |
A Javascript function that is passed the value of the tick. The return value is displayed on the graph. |
sampleSize |
The number of ticks to examine when deciding how many labels will fit. Setting a smaller value will render faster, but is less accurate in cases with large variance in label length. Defaults to sampling all ticks. |
autoSkip |
If true, automatically calculates how many labels can be shown and hides labels that will overlap. Labels will be rotated up to maxRotation before skipping. Turn autoSkip off to show all labels no matter what. Defaults to true. |
autoSkipPadding |
Padding between ticks on the horizontal axis when autoSkip is enabled. Defaults to 0 |
labelOffset |
Distance in pixels to offset the label from the center point of the tick. Defaults to 0 |
maxRotation |
Maximum rotation for tick labels in degrees. Labels are rotated to make room for other labels. Only applies to horizontal scales. Defaults to 50 |
minRotation |
Minimum rotation for tick labels. Only applies to horizontal scales. Defaults to 0. |
mirror |
If true, flips tick labels around the axis, displaying them inside the chart instead of outside. Only applicable to vertical scales. Defaults to false. |
padding |
Padding between tick labels and the axis, in pixels. Defaults to 0. |
Below is an example that formats Y axis ticks as currency. The callback
function localizes the currency, adding commas (or other delimeter) to the thousands place. You can use this technique to add percentage symbols and other label formats to your chart:
Writing a Javascript function can be a hassle. If your labels are not complex, the built-in tickFormat plugin allows you to apply common formatting needs without having to write Javascript. This can be simpler than writing the code yourself.
Use options.plugins.tickFormat to set options for formatting axis tick labels. The tickFormat object supports locale
, prefix
, suffix
attributes, as well as all options supported by Javascript's Intl.NumberFormat.
Attribute Name | Description |
---|---|
locale |
An Intl.Locale string such as en-US (default), fr-FR, de-DE, en-GB. Full list here |
prefix |
String to prepend to tick label |
suffix |
String to append to tick label |
style |
The formatting style to use. Default is decimal .
|
currency |
The currency to use in currency formatting. Possible values are the ISO 4217 currency codes, such as USD for the US dollar or EUR for the euro. Requires style=currency |
unit |
The unit to use in unit formatting, such as kilometers, megabyte, percent, etc. Must be a supported unit. Requires style=unit |
minimumFractionDigits |
The minimum number of fraction digits to use. Useful to determine the number of decimals shown. |
useGrouping |
true to display grouping separators in numbers, such as the thousands separator. false to disable. Defaults true. |
More options | Number formatting is highly configurable. View Intl.NumberFormat documentation for the full list of options, including ability to control significant digits, scientific and engineering notation, and so on. |
In this example, we add thousands commas to numbers on the numeric axis:
// ... Add commas or decimals
options: {
plugins: {
tickFormat: {
locale: 'en-US', // en-US is the default locale
useGrouping: true
}
}
}
This example will put a dollar symbol before each value and display two decimals of precision:
// ... Show as currency
options: {
plugins: {
tickFormat: {
style: 'currency',
currency: 'USD',
minimumFractionDigits: 2,
}
}
}
This tick formatter will append the letter "k" to every value:
// ... Add suffix
options: {
plugins: {
tickFormat: {
suffix: 'k'
}
}
}
QuickChart supports the Chart.js data labels plugin for adding custom data labels in your chart area. Labels can be added to an assortment of chart types, including bar, line, and scatter.
See this example configuration using datalabels.
Learn more:
All labels support the newline character, \n
. Use this character to introduce a line break.
In order to extend annotation and labeling capabilities beyond Chart.js defaults, we provide three additional Chart.js plugins: Data Labels (chartjs-plugin-datalabels), Annotations (chartjs-plugin-annotation), and Outlabels (chartjs-plugin-piechart-outlabels). These allow you to add various markup to your chart. Have a look at the documentation for each plugin to learn more about the possibilities.
An example of Chart.js data labels and annotations:
An example of the outlabeledPie
type:
The chart legend can be customized via the options.legend property (more information on chart legend).
In the example below, we choose to show the legend by setting display to true, and then set the position and align properties to move it where we want to see it.
QuickChart supports all Google Noto fonts. Custom fonts are available upon request.
To change font size and style, you may set values for each component of the graph:
The example below displays a number of chart font size, style, and color customizations for each component of the chart:
Every aspect of chart coloration is customizable. All colors are taken as strings, in either hex, RGB, or by specifying a color name. To adjust opacity, set an RGBA value.
To color the chart background, set the backgroundColor
query parameter to fill the entire chart background. See API parameters.
To color data series, set the borderColor
and backgroundColor
properties on each dataset in your chart (datasets defined in data.datasets
in the chart configuration object).
The default color palette is based on Tableau's and is carefully designed to work well together yet remain distinct and friendly to conditions such as color blindness. You may specify select color schemes from the Chart.js colorschemes plugin, which offers predefined and well-known color schemes.
To customize font and label colors, see font customization.
To customize gridline and axis colors, reference gridlines documentation.
To use a custom background image, use the backgroundImageUrl
plugin. The image must be publicly available on the web, load within 5 seconds, and be in png, jpg, gif, bmp, tiff, svg, or webp format:
// ...
options: {
plugins: {
backgroundImageUrl: 'https://example.com/image.png'
}
}
To add a gradient fill, use getGradientFillHelper(direction, colors, dimensions)
.
Parameter | Description |
---|---|
direction | The direction of the gradient. horizontal , vertical , or both . |
colors | A list of colors that defines the gradient. Colors can be specified in named, hex, or rgb/rgba formats. |
dimensions | Optional. An object with width and height parameters that defines the size of the gradient. |
Here's an example chart configuration:
{
type: 'bar',
data: {
labels: [2012, 2013, 2014, 2015, 2016],
datasets: [{
label: 'Gradient example',
data: [12, 6, 5, 18, 12],
backgroundColor: getGradientFillHelper('vertical', ["#36a2eb", "#a336eb", "#eb3639"]),
}]
}
}
For advanced coloration and backgrounds, see chart gallery - patterns and fills for gradients, patterns, background images, image fills, and more.
Points (also referred to as "markers") may appear in a line, sparkline, radar, or bubble chart. Point style can be configured globally using the options.elements.point object. See Chart.js point configuration for more details. You may configure the following properties on the options.elements.point
object:
Name | Description |
---|---|
backgroundColor |
Fill color for points with inner space (e.g. circle, triangle) |
borderColor |
Color for points without inner space (e.g. star), border color for points with inner space (e.g. circle, triangle) |
borderWidth |
Border width in pixels. Defaults to 1 |
radius |
Point radius in pixels |
rotation |
Rotation of point shape, in degrees |
pointStyle |
Determines the shape of the point. Use this to customize the markers on your charts. One of the following values: circle, cross, crossRot, dash, line, rect, rectRounded, rectRot, star, triangle . Paid accounts may also use a custom image as a point.
|
To configure only the points for a specific data series, have a look at the Chart.js documentation for individual dataset properties. In particular, lines and radar charts can customize their points by setting the following. You may configure the following properties on the datasets
object.
Name | Description |
---|---|
pointBackgroundColor |
Fill color for points with inner space (e.g. circle, triangle) |
pointBorderColor |
Color for points without inner space (e.g. star), border color for points with inner space (e.g. circle, triangle) |
pointBorderWidth |
Border width in pixels. Defaults to 1 |
pointRadius |
Point radius in pixels |
pointRotation |
Rotation of point shape, in degrees |
pointStyle |
Determines the shape of the point. One of the following values: circle, cross, crossRot, dash, line, rect, rectRounded, rectRot, star, triangle . Paid accounts may also use a custom image as a point.
|
For live examples of charts with different point styles, see the chart gallery.
You can style lines by setting properties on the data.dataset object that defines your line series. See Chart.js line styling documentation for full details.
The following are useful styling properties that are available on the line object:
Name | Description |
---|---|
backgroundColor |
The color of area filled under the chart. |
borderCapStyle |
Cap style of the line. See MDN. |
borderColor |
The line color. |
borderDash |
Length and spacing of line dashes. Use this to create dashed or dotted lines. For example, a simple dashed line would be [2, 2]. See MDN. |
borderDashOffset |
Offset for line dashes. See MDN. |
borderJoinStyle |
Line joint style. See MDN. |
borderWidth |
The line width, in pixels. |
clip |
How to clip relative to chartArea. Positive value allows overflow, negative value clips that many pixels inside chartArea. 0 = clip at chartArea. Clipping can also be configured per side: clip: {left: 5, top: false, right: -2, bottom: 0} |
fill |
Set true to fill in area under the chart. |
lineTension |
Bezier curve tension of the line. Set to 0 to draw straightlines. Set 0.4 for line smoothing. |
showLine |
If false, the line is not drawn for this dataset. |
spanGaps |
If true, lines will be drawn between points with no or null data. If false, points with NaN data will create a break in the line. |
steppedLine |
If true, draw line as a stepped line. Other valid values include before for step-before interpolation, after for step-after interpolation, and middle for step-middle interpolation.
|
Line charts can be smoothed by setting the lineTension attribute on the dataset. For example:
{
data: {
datasets: [{
// ...
lineTension: 0.4
}]
}
}
A built-in plugin is available to users who want to round the corners of their bar charts. To round corners, set options.plugins.roundedBars to true:
{
// ...
options: {
plugins: {
roundedBars: true
}
}
}
You may also specify the pixel radius of the rounded corners using the cornerRadius property:
{
// ...
options: {
plugins: {
roundedBars: {
cornerRadius: 20
}
}
}
}
Date and time series axes automatically handle calendar dates. To create a time series axis, set its type to time. For example:
{
// ...
options: {
scales: {
xAxes: [{
type: 'time'
}]
}
}
}
In order to use this axis, specify your data as XY coordinates, with X values defining the dates:
data: [{
x: new Date('1990-10-25'),
y: 1
}, {
x: new Date(), // Default to now
y: 10
}]
You don't have to use a Date
object. Strings are converted from most unambiguous date formats using moment.js:
data: [{
x: '25 Oct 1990 06:00',
y: 1
}, {
x: '1990-10-26 14:00',
y: 10
}]
Further configuration is possible by providing a time object to the scale. All parameters below are optional:
Name | Description |
---|---|
unit |
If set, force the axis unit to be this type. If not set, an appropriate unit will be automatically detected. Supported units: millisecond, second, minute, hour, day, week, month, quarter, year . |
minUnit |
The minimum unit of time to display. |
stepSize |
The number of units between gridlines |
displayFormats |
Customizes how different time units are displayed on the chart. See docs for detail on how to set this object. |
isoWeekday |
If true, set the first day of the week to Monday. Otherwise, defaults to Sunday |
parser |
Customizes the parser for datetime values in the data object. See moment.js for valid date string formats (e.g. YYYY MMM D h:mm:ss ). |
round |
If set, dates will be rounded to the start of this unit. See supported time units above. |
In this configuration example, we use a custom datetime parser and a custom display:
For more advanced usage, learn about Time Cartesian axes.
Use retina support to generate high quality images suitable for high-DPI displays. By default, QuickChart serves charts at 2x requested pixel size so that they appear sharp on retina displays.
To disable retina support set the devicePixelRatio parameter to 1.0 (see query parameters documentation). devicePixelRatio acts as a multiplier on the width and height of your chart.
Simple chart configs are defined using only JSON, but more complex chart configs may include Javascript functions. QuickChart accepts charts containing Javascript.
If you're using a GET request, all you need to do is include your function in the chart definition. If you're using a POST request, make sure you send the chart
parameter as a string rather than a JSON object.
You may POST the following data. Note that this payload is valid JSON and the chart
object is a string containing Javascript or JSON:
{
"backgroundColor": "transparent",
"width": 500,
"height": 300,
"format": "png",
"chart": "{type:'bar',data:{labels:['January','February','March','April','May'],datasets:[{label:'Dogs',data:[50,60,70,180,190]}]},options:{scales:{yAxes:[{ticks:{callback:function(value){return'$'+value;}}}]}}}"
}
Put the above JSON in a file called chart_request.json
and send it via curl:
$ curl -X POST \
-H "Content-Type: application/json" \
-d @chart_request.json \
'https://quickchart.io/chart' > chart.png
Or use any other programming language's ability to send an HTTP POST request.
Below are a few Javascript examples showing how to build a chart definition containing a function:
Option 1: Build the config as a string, not an object. This is the most straightforward way.
const chartStr = `{
type: 'bar',
data: {
labels: ['January', 'February', 'March', 'April', 'May'],
datasets: [{
label: 'Dogs',
data: [ 50, 60, 70, 180, 190 ]
}]
},
options: {
scales: {
yAxes: [{
ticks: {
callback: function(value) {
return '$' + value;
}
}
}],
},
},
}`;
console.log(encodeURIComponent(chartStr));
Option 2: Construct your chart as a JSON object. Later, substitute your Javascript function.
const chartObj = {
type: 'bar',
data: {
labels: ['January', 'February', 'March', 'April', 'May'],
datasets: [{
label: 'Dogs',
data: [ 50, 60, 70, 180, 190 ]
}]
},
options: {
scales: {
yAxes: [{
ticks: {
callback: '__CALLBACK_PLACEHOLDER__',
}
}],
},
},
};
const myFormatterFunction = function(value) {
return "$" + value
};
const chartStr = JSON.stringify(chartObj).replace('"__CALLBACK_PLACEHOLDER__"', myFormatterFunction.toString());
console.log(encodeURIComponent(chartStr));
Option 3: Serialize a normal Javascript object containing a function using javascript-stringify. This is probably the easiest to work with but it requires an external dependency.
const { stringify } = require('javascript-stringify');
const chartObj = {
type: 'bar',
data: {
labels: ['January', 'February', 'March', 'April', 'May'],
datasets: [{
label: 'Dogs',
data: [ 50, 60, 70, 180, 190 ]
}]
},
options: {
scales: {
yAxes: [{
ticks: {
callback: function(value) {
return '$' + value;
}
}
}],
},
},
};
console.log(encodeURIComponent(stringify(chartObj)));
QuickChart comes with several Chart.js plugins pre-installed. They are:
Use these plugins as you please in your chart config - no need to import anything extra. Note that Chart.js v3 only supports datalabels and annotation plugins.
As with any Chart.js chart, it's possible to add custom inline plugins by setting the plugins
attribute in your chart config.
Setting a custom plugins
object will override the plugins built into QuickChart.
Here's an example that adds some extra space between a pie chart and its legend. Note that the global Chart
object is available to the plugin:
{
"type": "pie",
"data": {
"labels": ["Yes", "No", "Maybe"],
"datasets": [{
"backgroundColor": ["#FF3784", "#36A2EB", "#4BC0C0"],
"data": [3, 24, 12]
}]
},
"plugins": [{
"beforeInit": function(chart, options) {
Chart.Legend.prototype.afterFit = function() {
// Add 50 pixels of height below the legend.
this.height = this.height + 50;
};
}
}]
}
It is also possible to add a logo to charts or watermark a chart. For more information, see our Watermark API.
How can I make my chart look like X?
QuickChart uses the popular open-source Chart.js library, so you can use all Chart.js documentation and Chart.js-related search terms to answer questions on how to customize your chart. If you're stuck, feel free to email us.
Do I need a license to use QuickChart?
Users of QuickChart's paid versions retain full copyright to images they generate. Charts generated by QuickChart's free version are public domain, meaning you are free to use them for any purpose.
If you'd like to fork the code, keep in mind this project is licensed under GPLv3 and you should make your code public and retain the copyright notice. If you'd like to license QuickChart privately or commercially, or if you'd like help setting up a private instance, please get in touch.
Is this a suitable replacement for Google Image Charts?
This service is a replacement for the Google Image Charts API, which turned off on March 14, 2019. QuickChart provides a drop-in replacement for Google Image Charts documented here.
QuickChart encourages the use of Chart.js format over the deprecated Google Image Charts format. Although Chart.js doesn't match exactly with the Google Image Charts API, it is a more flexible, general-purpose charting specification. Both Chart.js and QuickChart have strong open-source communities.
We encourage developers to choose a fully open-source solution over proprietary services in order to mitigate risk and future-proof their choice of API.
How reliable is QuickChart?
This service (QuickChart.io) is widely used and generates over 300 million charts per month. It is hosted on a large cluster of redundant servers. There is a built-in rate limit of 60 charts/min (1 chart/sec) and 10,000 charts/month for free users.
If you want to adjust rate limits or need a Service-Level Agreement with uptime guarantees, purchase a license or get in touch.
See also the QuickChart status page, which monitors uptime.
How can I contribute?
QuickChart is under active development. If you'd like to suggest a feature or modify QuickChart code, please open an issue or pull request on the QuickChart Github.