Skip to content

Chart Templates

Chart Templates provide a convenient way to create and customize various types of charts using a simple URL-based API.

By setting different URL parameters, you can easily modify the chart’s attributes to visualize your data in different ways.

You can reuse the same chart template and produce many variations of the original chart.

Templating works with Interactive Charts, Images, Embedded Charts, and Embedded Images.

Share & Template Dialog

Open the Share & Template dialog from the main toolbar. On the left side tab panel, click Templates.

Templates are currently turned off on the current chart
Templates are currently turned off on the current chart

Turn on a template

Click the template toggle to enable or disable templating for the current chart.

Once the template has been turned on, many templating options will appear.

Template Settings

Templates settings and url params to customize the template url
Templates settings and url params to customize the template url

Similar to a shared interactive chart, shared interactive chart templates have the same settings.

  • Show Data Whether to show the data tab in the interactive template
  • Show Chart Whether to show the chart tab in the interactive template
  • Show Editor Control Whether to show the editor controls in the interactive template
  • Template Title A custom title to display in the interactive template

Url Customization

Use the url customization section of the Templates dialog to customize the sample template generated for you.

Change the generated params with data param values below.

Basic Usage

To create a chart, simply construct a URL using the following base template:

https://instacharts.io/app/template/share/{templateId}?{parameters} Replace {templateId} with the template id from the Share & Templates dialog from a chart you’d like alter. Add any necessary parameters to customize the chart’s appearance and data.

Data is changed with the x,y, and z params: https://instacharts.io/app/template/share/0c62df03-a874-490a-ab8c-6d734a97a133?x=[Apples,Oranges,Pears,Peaches,Lemons]&y=[1,2,3,4,5]

Chart type is changed with the type param: https://instacharts.io/app/template/share/0c62df03-a874-490a-ab8c-6d734a97a133?type=bar

Base URLS

Depending on where and how you’d like to view your customized chart, there are several different base urls available:

Shared Interactive Chart

The chart will appear as a standalone webpage. Users will be able to hover over datapoints in the chart, view underlying data, and edit the chart if the editor controls are turned on.

Shared Interactive Chart base url: https://instacharts.io/app/template/share/{templateId}?{parameters}

Image

The chart will appear as a static png image.

Note: images can take anywhere from a few seconds to 30 seconds (for very data intensive charts) to create. Plan accordingly.

Image base url: https://instacharts.io/app/img/{templateId}?{parameters}

Embedded Interactive Chart

The chart will be in an iframe, that is made for embedding into webpages. Users will be able to hover over datapoints in the chart, view underlying data, and open the chart into a new tab to view it larger.

Embedded Interactive Chart base url: https://instacharts.io/app/template/embeds/{templateId}?{parameters}

Available Parameters

The following parameters can be used to modify the chart’s attributes:

Data Params

These replace the data shown in the chart.

ParameterDescriptionExample
xData for the X Axis&x=[Action,Thriller,Suspense]
yData for the Y Axis&y=[100,450,750]
zData for the Group Axis (if there is one)&z=[G,PG,PG]

Chart Toolbar Params

These can be set in the template from the main chart toolbar.

ParameterDescriptionExample
typeChart Type&type=stackedBar
aggregateAggregation function&aggregate=sum
xTimeUnitTime Unit for X Axis (if it is a date)&xTimeUnit=monthyear
yTimeUnitTime Unit for Y Axis (if it is a date)&yTimeUnit=monthyear
zTimeUnitTime Unit for Z Axis (if it is a date)&zTimeUnit=monthyear

Chart Type Values

These are the possible chart type values

Chart TypeDescriptionExample
barBar chart&type=bar
stackedBarStacked Bar chart&type=stackedBar
groupedBarGrouped Bar chart&type=groupedBar
lineLine chart&type=line
groupedLineGrouped Line chart&type=groupedLine
scatterScatter chart&type=scatter
groupedScatterGrouped Scatter chart&type=groupedScatter
areaArea chart&type=area
groupedAreaGrouped Area chart&type=groupedArea
piePie chart&type=pie

Aggregate Values

These are the possible aggregate values

AggregateDescriptionExample
sumPerform a summation - Add all values together&aggregate=sum
countCount number of rows&aggregate=count
averageCalculate the average of all values&aggregate=average
medianFind the median (or middle value)&aggregate=median
minMin - find the smallest value&aggregate=min
maxMax- find the largest values&aggregate=max
distinctCount the number of rows with distinct(different) values&aggregate=distinct
validCount the number of rows with a value&aggregate=valid
missingCount the number of rows missing a value&aggregate=missing

Time Unit Values

These are the possible time unit values. These values can be applied to xTimeUnit, yTimeUnit, and zTimeUnit

Date Time Units

You can use the following day time units in any combination. Be sure to put them in order of longest time value to shortest. The day time units are year, month, date, hour, minutes

Here are some examples:

Time UnitDescriptionSample DateExample
yearYear2024&xTimeUnit=year
year_monthMonth and yearJan 2024, Jan 2025&xTimeUnit=year_month
year_month_dateMonth date and yearJan 1, 2024&xTimeUnit=year_month_date
month_dateMonth and dateFeb 2&xTimeUnit=month_date
hours_minutesHours and minutes17:32&xTimeUnit=hours_minutes
month_date_hoursMonth and date with hoursJan 28 05:00&xTimeUnit=month_date_hours

Interval Time Units

The interval time units have fewer combinations than the date time units. Most interval time units only combine with year The interval time units are week, quarter, day, dayofyear

Here are some examples:

Time UnitDescriptionSample DateExample
quarterQuarter of the year (1-4)Q3&xTimeUnit=quarter
year_quarterQuarter and year2024 Q4&xTimeUnit=year_quarter
weekWeek of the year (1-52)W52&xTimeUnit=week
year_weekWeek of the year with year2024 W52&xTimeUnit=year_week
dayDay of the weekSun, Mon, Tues&xTimeUnit=day
dayofyearDay of the year (1-365)235&xTimeUnit=dayofyear
year_dayofyearDay of the year with year2024 365&xTimeUnit=year_dayofyear

Text Params

Set the default value for these params in the template on the left sidebar under Chart Text.

ParameterDescriptionExample
titleThe title of the chart&title='2024 Olympic Gold Medals'
subtitleThe subtitle of the chart&subtitle=Highlighted by Country
titleAlignAlignment of the chart title&titleAlign=0
showAxisLabelsSet to false to hide the X and Y Axis Labels&showAxisLabels=false
numberLocaleLocale used to format numbers&numberLocale=1
timeLocaleLocale used to format dates&timeLocale=2
xNumFormatNumber format used on the X axis&xNumFormat=0
yNumFormatNumber format used on the Y axis&yNumFormat=1
zNumFormatNumber format used on the Group or legend axis&zNumFormat=1
xTitleThe title of the X axis&xTitle=Event
yTitleThe title of the Y axis&yTitle=Number of medals
zTitleThe title of the Group (or legend) axis&zTitle=Country

Legend Params

Set the default value for these params in the template on the left sidebar under Chart Text -> Legend.

ParameterDescriptionExample
legendShow or hide the legend&legend=true
legendDirLabel direction. 0 for horizontal, 1 for vertical&legendDir=1
legendNumVertColsNumber of vertical legend columns&legendNumVertCols=2
legendNumHorizColsNumber of horizontal legend columns&legendNumHorizCols=6
showLegendLabelShow or hide the legend title&showLegendLabel=true

Data Label Params

Set the default value for these params in the template on the left sidebar under Chart Text -> Data Labels.

ParameterDescriptionExample
dLabelShow or hide data labels&dLabel=true
dLabelPercentLabel removal %. Number between 0-20&dLabelPercent=1.5
dLabelPositionLabel position (see below)&dLabelPosition=1
dLabelBGShow label background&dLabelBG=true
dLabelOpacityBackground opacity. Number between 0-100&dLabelBGOpacity=50
dLabelTextColorText Color. 0 for Light, 1 for Dark.&dLabelTextColor=1

Label Position Values

ValueDescriptionExample
0Outside&dLabelPosition=0
1Inside Bottom (Inside Left - horizontal chart)&dLabelPosition=1
2Inside Center&dLabelPosition=2
3Inside Top (Inside Right - horizontal chart)&dLabelPosition=3

Size & Options Params

Set the default value for these params in the template on the left sidebar under Size & Options.

ParameterDescriptionExample
widthSet the width of the X-Axis in pixels&width=500
heightSet the height of the Y-Axis in pixels&height=450
autosizeLargeItemsSet to true to auto size charts with a large number of items (more than 20)&autosizeLargeItems=true
colorSchemeA color scheme for the chart (options are listed below)&colorScheme=tableau10
colorA single color for charts that only have 1 color (bar or line). This is a color hex code without the #&color=cccccc
normalizeSet to true to normalize the chart (% out of 100%)&normalize=true
switchAxisSet to true to switch bar charts to be horizontal instead of vertical&switchAxis=true

Color Scheme Values

ValueDescriptionTypeExample
tableau10TableauCategorical
&colorScheme=tableau10
tableau20Tableau 20Categorical
&colorScheme=tableau20
category20BCategory 20 BCategorical
&colorScheme=category20B
category20CCategory 20 CCategorical
&colorScheme=category20C
observable10ObservableCategorical
&colorScheme=observable10
pairedPairedCategorical
&colorScheme=paired
pastel1PastelCategorical
&colorScheme=pastel1
viridisViridisSequential Multi-Hue
&colorScheme=viridis
magmaMagmaSequential Multi-Hue
&colorScheme=magma
plasmaPlasmaSequential Multi-Hue
&colorScheme=plasma
bluepurpleBlue PurpleSequential Multi-Hue
&colorScheme=bluepurple
redpurplePink PurpleSequential Multi-Hue
&colorScheme=redpurple
darkmultiDark MultiSequential Multi-Hue
&colorScheme=darkmulti
darkblueDark BlueSequential Multi-Hue
&colorScheme=darkblue
darkgreenDark GreenSequential Multi-Hue
&colorScheme=darkgreen
lightmultiLight MultiSequential Multi-Hue
&colorScheme=lightmulti
greenblueGreen BlueSequential Multi-Hue
&colorScheme=greenblue
goldredGold RedSequential Multi-Hue
&colorScheme=goldred
redyellowgreenRed Yellow GreenDiverging
&colorScheme=redyellowgreen
spectralSpectralDiverging
&colorScheme=spectral
rainbowRainbowCyclical
&colorScheme=rainbow
bluesBluesSequential Single-Hue
&colorScheme=blues
redsRedsSequential Single-Hue
&colorScheme=reds
tealsTealsSequential Single-Hue
&colorScheme=teals
purplesPurplesSequential Single-Hue
&colorScheme=purples
greensGreensSequential Single-Hue
&colorScheme=greens
warmgreysWarm GraysSequential Single-Hue
&colorScheme=warmgreys

Sort Params

Set the default value for these params in the template on the left sidebar under Size & Options -> Sorting.

ParameterDescriptionExample
sortAxisThe axis to sort the X-Axis by. 0 for auto sort, 1 for X-Axis and 2 for Y-Axis&sortAxis=0
sortDirectionThe direction to sort the X-Axis in. 0 for auto, 1 for ascending and 2 for descending&sortDirection=2
legendSortAxisThe axis to sort the legend by. 0 for auto sort, 1 for Group Axis and 2 for Y-Axis&legendSortAxis=1
legendSortDirectionThe direction to sort the legend in. 0 for auto, 1 for ascending and 2 for descending&legendSortDirection=2
piecesSortDirectionThe direction to sort stacked bar chart and pie chart pieces in. 0 for auto, 1 for ascending and 2 for descending&piecesSortDirection=0

Limit Items Params

Set the default value for these params in the template on the left sidebar under Limit Items -> Limit Items and Bins panels.

Limit Items ranks the chart’s values and keeps the largest or smallest number of items specified.

ParameterDescriptionExample
rankSet to true to limit the number of items in the chart through a ranking&rank=true
rankNumThe number of items to keep in the chart&rankNum=10
rankOthersGroup the rest of the items into an ‘All Others’ category&rankOthers=true
rankDirectionSet to 0 to keep the largest items, 1 to keep the smallest items&rankDirection=1
rankAxisSet to 0 to rank the items on the X-Axis, 1 for the Group Axis&rankAxis=0

Limit the number of items drawn by putting numerical values into ranges or bins. Ex: 50-100, 100-150, instead of plotting individual numbers

ParameterDescriptionExample
autoBinAutomatically apply bins on numerical axis&autoBin=true
autoBinXBin the X-Axis&autoBinX=false
autoBinZBin the Group Axis&autoBinZ=true

Filter Params

Set the default value for these params in the template on the left sidebar under Limit Items -> Filters.

ParameterDescriptionExample
removeXBlanksRemove null or blank values from the X-Axis&removeXBlanks=true
removeYBlanksRemove null or blank values from the Y-Axis&removeYBlanks=false
removeZBlanksRemove null or blank values from the Group Axis&removeZBlanks=true

Axis Min and Max Params

Set the default value for these params in the template on the left sidebar under Size & Options -> Numeric Axis Min & Max.

ParameterDescriptionExample
xAxisMinThe minimum value shown on the X-Axis&xAxisMin=1
xAxisMaxThe maximum value shown on the X-Axis&xAxisMax=20
yAxisMinThe minimum value shown on the Y-Axis&yAxisMin=0
yAxisMaxThe maximum value shown on the Y-Axis&yAxisMax=1000
zAxisMinThe minimum value shown on the Group Axis&zAxisMin=1
zAxisMaxThe maximum value shown on the Group Axis&zAxisMax=20

Trend Lines Params

Set the default value for these params in the template on the left sidebar under Annotate -> Trend Lines.

Multiple trend lines can be specified through the trendLines param. Each trend line should be enclosed in curly braces {} and separated by a comma. Colors and labels should be enclosed in single quotes '' .

Example of two trend lines specified: &trendLines=[{type:1, value:'', label:'Average Line', color:'181818', textColor:0, lineSize:1, lineType:0},{type:0, value:'6', label:'Custom 6', color:'54a24b', textColor:0, lineSize:'6', lineType:3}]

ParameterDescriptionExample
typeType of trend line to draw (listed below)&type=0
labelOptional line label text&label='Average Score'
colorline color as a hex color code without #&color='ddddddd'
textColorText color. 0 for light, 1 for dark&textColor=1
lineSizeLine thickness - Number from 1 - 99&lineSize=1
lineTypeLine pattern (listed below)&lineType=1

Type

TypeValueDescriptionExample
Custom Value0Highlight a specific value with a line on the Y-Axis&type=0
Average1A line through the average value on the Y-Axis&type=1
Median2A line through the median value of the Y-Axis&type=2
Linear Regression3A best fit line&type=3
Loess Regression4A best fit curve&type=4

Line Type

Line TypeValueExample
Solid0&lineType=0
Small Dots1&lineType=1
Small Dashes2&lineType=2
Medium Dashes3&lineType=3
Large Dashes4&lineType=4
XL Dashes5&lineType=5

Axis Style Params

Set the default value for these params in the template on the left sidebar under Size & Options -> Grid Style, Axis Style panels.

Grid Style

ParameterDescriptionExample
gridLineOpacityThe opacity of the grid lines on the Y-Axis. (value between 0-100)&gridLineOpacity=0
gridOutlineSet to true to show an outline around the chart grid&gridOutline=false

X-Axis Style

ParameterDescriptionExample
xLabelOpacityThe opacity of the labels on the X-Axis. (value between 0-100)&xLabelOpacity=50
xTickOpacityThe opacity of the tick marks on the X-Axis. (value between 0-100)&xTickOpacity=true
xAxisLineOpacityThe opacity of the axis line on the X-Axis. (value between 0-100)&xAxisLineOpacity=50
xTitleOpacityThe opacity of the axis title on the X-Axis. (value between 0-100)&xTitleOpacity=50
xTickCountEstimated number of tick marks or values to show on the X-Axis&xTickCount=4

Y-Axis Style

ParameterDescriptionExample
yLabelOpacityThe opacity of the labels on the Y-Axis. (value between 0-100)&yLabelOpacity=50
yTickOpacityThe opacity of the tick marks on the Y-Axis. (value between 0-100)&yTickOpacity=true
yAxisLineOpacityThe opacity of the axis line on the Y-Axis. (value between 0-100)&yAxisLineOpacity=50
yTitleOpacityThe opacity of the axis title on the Y-Axis. (value between 0-100)&yTitleOpacity=50
yTickCountEstimated number of tick marks or values to show on the Y-Axis&yTickCount=4