Instance Options
A separate chart instance is created for each targetted division and may have its own settings:
$(selector).gchart({series: [...]});
Below are the options that may be applied to each Google chart instance.
Although all are optional, you probably want to provide at least the data values
to be plotted via the series
setting.
axes | backgroundColor | barGroupSpacing | barSpacing | barWidth | barZeroPoint | chartColor | dataLabels | encoding | extension | format | functions | gridLine | gridOffsets | gridSize | height | icons | legend | legendColor | legendDims | legendOrder | legendSize | mapArea | mapColors | mapDefaultColor | mapLatLong | mapRegions | margins | markers | maxValue | minValue | onLoad | opacity | pieOrientation | provideJSON | qrECLevel | qrMargin | ranges | secure | series | title | titleColor | titleSize | type | usePost | visibleSeries | width
Name | Type | Default | Comments |
---|---|---|---|
width | number | 0 | Set the width of the desired chart. If not set explicitly it defaults to the width of its containing division. Google imposes size restrictions on the charts, being 1000 pixels in either direction, but with an overall maximum of 300,000 pixels in area (e.g. 1000 x 300, 600 x 500). If either dimension exceeds 1000 it is reduced to this amount. If the image size is greater than the area limit the height is recalculated so that it is valid again. Map charts are restricted to 600 pixels in either direction, but with an overall maximum of 300,000 pixels. |
height | number | 0 | Set the height of the desired chart. If not set explicitly
it defaults to the height of its containing division.
See width for restrictions. |
format | string | 'png' | Set the image format to be returned: 'png' or 'gif'. Since 1.3.1. |
usePost | boolean | false | Google charts normally uses a GET URL, which is limited to 2K in size.
For larger charts, set this setting to true to use POST instead.
This allows for requests up to 16K in size, but requires that the chart appear
within an iframe that is embedded in your containing division.Since 1.3.1. |
secure | boolean | false | Google charts normally uses an open line (HTTP). Set this setting to
true to encrypt (HTTPS) the request instead.Since 1.4.1. |
margins | number or number[2] or number[4] | null | Set the minimum margins around the chart. The value may be a single number
representing identical margins all around or an array containing either
left/right and top/bottom margins or left, right, top, and bottom
margins in pixels. Leave as null for default margins.Since 1.2.0. |
title | string | '' | Set the title of the chart as a whole. Include pipe (|) characters to indicate new lines. |
titleColor | string | '' | Set the colour of the title. Defaults to 'black'. See the section on colour for more details. |
titleSize | number | 0 | Set the font size (points) of the chart title. Defaults to 14. |
opacity | number | 0 | Set the opacity of the chart as a whole. The value may be specified either
in the range 0.0 to 1.0, or as a percentage from 0 to 100, with the
higher values indicating fully opaque. Leave as zero for fully opaque. Since 1.3.0. |
backgroundColor | string or object | null | Set the background colour to be used for the entire image.
See the section on
colour for more details. If more than a single colour is required you can set this option to an object with the following attributes: angle (string or number) either a descriptive term
for the angle ('horizontal' for left to right, 'vertical' for
bottom to top, 'diagonalUp' for bottom/left to top/right, or
'diagonalDown' for top/left to bottom/right) or
the number of degrees from the positive x-axis (may be negative),striped (boolean) true for a series of distinct stripes
or false for a continuous gradient,colorPoints ([][2]) an array of two-item arrays containing
a colour and an offset from 0.0 (bottom/left) to 1.0 (top/right).See the gradient and
stripe functions for
an easy way to create simple gradients and stripes.
|
chartColor | string or object | null | Set the background colour for the chart itself.
See backgroundColor
above for more details. |
legend | string | '' | Set the position of the legend: 'top', 'topVertical', 'bottom',
'bottomVertical', 'left', or 'right', or '' for none. Since 1.2.0 - added 'topVertical' and 'bottomVertical'. |
legendOrder | string | 'normal' | Set the order of entries in the legend: 'normal' (in the order given), 'reverse'
(in the reverse of the order given), 'automatic' (order by length), or a list of
indexes (zero-based) separated by commas (,).
Since 1.3.0. |
legendDims | number[2] | null | Set the minimum size of the legend. The array contains width and height
in pixels. Leave as null for default size. This setting is
ignored if margins is not set.Since 1.2.0. Since 1.4.1 - renamed from legendSize . |
legendColor | string | '' | Set the colour of the legend. Defaults to 'black'. Since 1.4.1. |
legendSize | number | 0 | Set the font size (points) of the legend. Defaults to 11. Since 1.4.1. |
type | string | 'pie3D' | Specify the type of chart required. line is a simple line chart with implied x-values. lineXY is a line chart with explicit x- and y-values. sparkline is a simple line chart with implied x-values and no axes. barHoriz is a bar chart oriented horizontally with stacked series. barVert is a bar chart oriented vertically with stacked series. barHorizGrouped is a bar chart oriented horizontally with side-by-side series. barVertGrouped is a bar chart oriented vertically with side-by-side series. barHorizOverlapped is a bar chart oriented horizontally with overlapping series. barVertOverlapped is a bar chart oriented vertically with overlapping series. pie is a two-dimensional pie chart showing a single series. pie3D is a three-dimensional pie chart showing a single series. pieConcentric is a two-dimensional pie chart showing multiple series in concentric rings. venn is a Venn diagram showing relationships between up to three sets, see the venn function (jquery.gchart.ext.js module)
for assistance in creating these diagrams.scatter is a chart of individual points specified as x- and y-values along with a size, see the scatter function (jquery.gchart.ext.js module)
for assistance in creating these charts.radar is a circular graph with values plotted out towards the perimeter, series are joined by straight lines. radarCurved is a circular graph with values plotted out towards the perimeter, series are joined by curved lines. map is a country or state map shaded based on data values, see the map function (jquery.gchart.ext.js module)
for assistance in creating these charts.mapOriginal is the old implementation of maps, see the map function (jquery.gchart.ext.js module)
for assistance in creating these charts.meter is a Google meter showing a single value, see the meter function (jquery.gchart.ext.js module)
for assistance in creating these charts.qrCode is a two-dimensional bar code that can encode text, see the qrCode function (jquery.gchart.ext.js module)
for assistance in creating these bar codes.formula is a mathematical formula, with the actual formula appearing as the single dataLabels value for the chart
using the TeX notation
(don't forget to escape any backslashes (\))
(requires the jquery.gchart.ext.js module).graphviz is a Graph Visualization showing an abstract graph or network - using the DOT language or the graphviz function (jquery.gchart.graphviz.js module)
to define the graph.Since 1.2.0 - added 'pieConcentric'. Since 1.3.0 - added 'formula'. Since 1.3.2 - added 'graphviz'. Since 1.3.3 - added 'barHorizOverlapped', 'barVertOverlapped', 'mapOriginal'. Since 1.4.0 - moved 'formula', 'map', 'mapOriginal', 'meter', 'qrCode', 'scatter', and 'venn' to the jquery.gchart.ext.js module;
moved 'graphviz' to the jquery.gchart.graphviz.js module. |
encoding | string | '' | Set the type of encoding of data values to be used. text normalises the values to 0-100 and presents them as normal text with commas (,) separating values and pipes (|) separating series (the default). scaled doesn't normalise the values and presents them as normal text with commas (,) separating values and pipes (|) separating series. simple normalises the values to 0-61 and presents them as one character (A-Za-z0-9) with no value separator and commas (,) separating series. extended normalises the values to 0-4095 and presents them as two characters (A-Za-z0-9-.) with no value separator and commas (,) separating series. |
series | object[] | [this.series('Hello World', [60, 40])] | Provide the data values to be charted. You can create the
series objects directly or you can use the
series function to generate a new series object.
Since an x-y line chart requires a special format
for the series, you should use the
seriesForXYLines
function to assist in that case.
Series data can also be loaded from external sources via the
seriesFromCsv and
seriesFromXml functions.Each entry in the array is an object with the following attributes: label (string, optional) the display text for this series,data (number[]) the data values to be plotted,color (string or string[], optional) the colour for the series -
see the section on
colour for more details; provide an array to specify colours
for each item in the series; if fewer colours than the number of segments
are given, the colours are recycled for the remaining segments,fillColor (string, optional) the background colour between
this series and the next one or a
gradient
or stripe
definition with which to fill the current bar,minValue (number, optional) the minimum value for this series,maxValue (number, optional) the maximum value for this series,lineThickness (number, optional together with lineSegments )
the width (pixels) of the line for this series,lineSegments (number[2], optional together with lineThickness )
the lengths (pixels) of line segments and gaps when drawing the line for this series.
Since 1.2.0 - color may be an array.Since 1.4.2 - fillColor may be a gradient or stripe. |
visibleSeries | number | 0 | Indicate how many series should be drawn directly. The remainder are still available
for use with markers. A value of 0 means that all series should be drawn.
The visible series must appear first in the list of series. Since 1.2.0. |
dataLabels | string[] | [] | Specify the labels to apply to each of the data items in the series. Whereas the series labels apply to the entire series, these labels apply to all the first, second, etc. items across all the series. |
functions | object[] | [] | Add
data functions to be applied to your chart.
You can use the
fn and
fnVar functions to assist in creating data function definitions.Each entry in the array is an object with the following attributes: series (number) the target series into which
the calculated values are written; often this would be a dummy series
($.gchart.series([0]) ),data (object or object[]) one or more variable definitions for
this function; use the
fnVar function to create variable definitions,fnText (string) the function to evaluate for each input value; it is
specified using
muParser function syntax.
Since 1.3.3. |
axes | object[] | [] | Define any number of axis labels for your chart,
including multiple sets of labels for one axis.
Default labels range from 0 to 100 with 10 steps in between.
You can use the
axis function to assist in creating axis definitions
and the GChartAxis functions to modify them.Each entry in the array is either a string giving the axis name or a GChartAxis object with the following attributes:_axis (string) the name of the axis to which this
definition applies ('top', 'left' or 'y', 'bottom' or 'x', 'right'),_lineColor (string, optional) the text colour for the labels;
see the section on
colour for more details,_labels (string[], optional) the text labels to appear along this axis;
unless positioned as described below, these labels are evenly spaced
along the axis starting and ending at the edges of the chart;
if omitted numeric labels corresponding to each tenth of the range are shown,_positions (number[], optional) the positions of the labels along the
axis ranging from the range start (0 by default) at the bottom/left
to the range end (100 by default) at the top/right;
if positions are defined but no labels are supplied,
then these values become the labels as well,_range (number[2 or 3], optional) the start and end points of the range
of values depicted, which may be given as highest to lowest to invert the labels;
an optional third entry specifies the interval between points in the range;
if not specified a range of 0 to 100 and an interval of 1/10th the range is assumed,_color (string, optional) the text colour for the labels;
see the section on
colour for more details,_alignment (string, optional) the alignment of the labels
('left', 'center', 'right'); the default alignment changes per axis,_size (number, optional) the size (pixels) of the text for the labels,_drawing (string, optional) the drawing control to specify
what is drawn for the axis ('line', 'ticks', 'both' (default)),_tickColor (string, optional) the colour of the tick marks;
defaults to axis colour,_tickLength (number or number[], optional) the length of the tick marks
or an array of lengths to cycle through;
negative values are drawn inside the chart; the maximum positive value is 25,_format (object, optional) formatting definition for the
axis values.
Since 1.2.0 - added _drawing ,
_tickColor , and _tickLength attributes.Since 1.3.0 - added _format attribute.Since 1.4.1 - added _lineColour attribute,
_tickLength can be an array. |
ranges | object[] | [] | Define any number of data ranges to display on your chart.
You can use the
range function to assist in creating range definitions.
Each entry in the array is an object with the following attributes:vertical (boolean, optional) true to draw the range
vertically across the chart or false to draw it horizontally,color (string) the colour to be used for this range;
see the section on
colour for more details,start (number) the starting value for the range
between 0.0 at the bottom/left and 1.0 at the top/right,end (number, optional) the ending value for the range
between 0.0 at the bottom/left and 1.0 at the top/right;
if omitted a line is drawn rather than a rectangular area.
|
markers | object[] | [] | Define any number of markers to display on your chart.
You can use the
marker function to assist in creating marker definitions.
Each entry in the array is an object with the following attributes:shape (string) the type of shape to draw for this marker
('annotation', 'arrow', 'candlestick', 'circle', 'cross', 'diamond', 'down',
'errorbar', 'flag', 'financial', 'horizbar', 'horizontal', 'number', 'plus',
'rectangle', 'sparkfill', 'sparkline', 'sparkslice', 'square', 'text', 'vertical'),color (string) the colour to be used for this marker;
see the section on
colour below for more details,series (number, optinal) the index of the series
to which this marker applies (0 (default) to n),item (number or string or number[2 or 3], optional) the index of
the point within that series to which this marker applies (0-n)
or -1 or 'all' for all points in that series (the default)
or 'everyn' where n is a number to regularly space the markers
or 'everyn[start:end]' where the values are numbers
to regularly space the markers within the given range of points
or [start, end, every] to only apply markers
to the specified range of points and optionally evenly space them
or [x, y] positions (see positioned below),size (number, optional) the size (pixels) for this marker (default 10),priority (string or number, optional) the rendering priority of
this marker ('behind' or -1, 'normal' or 0 (the default), 'above' or +1),text (string, optional) the text to show
if this is a 'text' or 'flag' type marker or the number format
for a 'number' type marker - see the
numberFormat
function for formatting options,positioned (boolean, optional) true to absolutely position
the marker - the item value must be an array of two values
in the range 0.0 to 1.0placement (string or string[], optional) the placement
justification(s) ('left', 'center' or 'centre', 'right', 'top', 'middle',
'bottom', 'barbase', 'barcenter' or 'barcentre', 'bartop'),offsets (number[2], optional) the pixel offsets, horizontal
and vertical, from the calculated position.
Since 1.1.0 - 'sparkfill' and 'sparkline' types. Since 1.2.0 - 'flag', 'financial', and 'number' types, ranges on item , positioned setting.Since 1.3.0 - 'annotation', 'errorbar', 'horizbar', 'rectangle', 'sparkslice' types, placement
and offsets settings.Since 1.3.1 - 'candlestick' as a synonym for 'financial' type. |
icons | object[] | [] | Define any number of
dynamic icons to display on your chart.
Requires the jquery.gchart.icons.js module.
You can use any of the
icon functions to assist in creating icon definitions.
Each entry in the array is an object with the following attributes:name (string) the full name of the icon,data (string) the encoded paramaters for this type of icon,series (number, optional) the index of the series
to which this icon applies (0 (default) to n) or -1 for freestanding,item (number or string or number[2 or 3], optional) the index of
the point within that series to which this icon applies (0-n)
or 'all' for all points in that series (the default)
or 'everyn' where n is a number to regularly space the markers
or [start, end, every] to only apply markers
to the specified range of points and optionally evenly space them,zIndex (number, optional) the z-index of
this icon from -1.0 (behind) through 0.0 (normal) to 1.0 (above),position (number[2], optional) the absolute position of
the icon centre from 0.0 (bottom/left) to 1.0 (top/right); if present
this override the series and item settings,offsets (number[2], optional) any pixel offsets from
the calculated position.
Since 1.3.0. Since 1.4.0 - moved to the jquery.gchart.icons.js module. |
minValue | number | 0 | The minimum value displayed on the chart.
Set to $.gchart.calculate to calculate the
minimum from the actual data values. |
maxValue | number | 100 | The maximum value displayed on the chart.
Set to $.gchart.calculate to calculate the
maximum from the actual data values. |
gridSize | number or number[2] | null | Specify the horizontal and vertical spacing (pixels)
between grid lines on the chart as either a single number that applies
for both or as an array of two numbers. Since 1.3.3 - can be a single number. |
gridLine | number or number[2] | null | Specify the appearance of the grid lines by providing the
lengths (pixels) of the line segments and the gaps between them as either
a single number that applies for both or as an array of two numbers.
A continuous line has a gap of zero. This setting is ignored
if gridSize hasn't been specified.Since 1.3.3 - can be a single number. |
gridOffsets | number or number[2] | null | Specify the offsets of the grid lines by providing the
x and y values (pixels) as either a single number that applies
for both or as an array of two numbers. This setting is ignored if
gridSize and gridLine haven't been specified.Since 1.2.0. Since 1.3.3 - can be a single number. |
extension | object | {} | Additional parameters may be passed to the Google chart request
via this object, whose attributes are transferred across. For example: {xyz: 4} would add &xyz=4 . |
barWidth | number or string | null | Specify the width (pixels) of the bars in a bar chart.
The width can also be set to $.gchart.barWidthAuto to
automatically resize the bars to fill the chart, or
$.gchart.barWidthRelative to resize the bars
based on the spacing between bars and groups being relative
to the width of a bar.Since 1.2.0 - can use $.gchart.barWidthAuto
or $.gchart.barWidthRelative . |
barSpacing | number | null | Specify the spacing (pixels) between the bars within a group in a bar chart.
This setting has no effect unless barWidth is also set.
If barWidth is $.gchart.barWidthRelative
the value should be between 0.0 and 1.0. |
barGroupSpacing | number | null | Specify the spacing (pixels) between groups of bars in a bar chart.
This setting has no effect unless barWidth and
barSpacing are also set.
If barWidth is $.gchart.barWidthRelative
the value should be between 0.0 and 1.0. |
barZeroPoint | number | null | Specify the position of the zero line in a bar chart, ranging from 0.0 at the bottom/left to 1.0 at the top/right. The bars in the chart then extend from this line up or down to the value for each data point. |
pieOrientation | number | 0 | Specify the starting angle for a pie chart in degrees clockwise
from the positive x-axis. Since 1.2.0. |
mapLatLong | boolean | false | Set to true to interpret mapArea
as latitude/longitude coordinates, rather than as pixel borders.
Requires the jquery.gchart.ext.js module.Since 1.3.3. Since 1.4.0 - moved to the jquery.gchart.ext.js module. |
mapArea | number or number[4] or string | null | Define the area to show in a map chart.
Requires the jquery.gchart.ext.js module.
By default all selected areas are shown
in the smallest surrounding box. You can override this by specifying a
single number to use as pixels border on all sides, or as an array of four
numbers for individual pixel borders (left, right, top, bottom) or
latitude/longitude limits (bottom, left, top, right) in conjunction with
the mapLatLong setting.Under the old map scheme, this value is a string to indicate the desired region: ('world', 'africa', 'asia', 'europe', 'middle_east', 'south_america', 'usa').
Since 1.3.3 - added pixel border and latitude/longitude options. Since 1.4.0 - moved to the jquery.gchart.ext.js module. |
mapRegions | string[] | [] | Specify the codes for the regions to be coloured on the map.
Requires the jquery.gchart.ext.js module. Use the appropriate
ISO 3166 country codes
to identify the regions. States and cities within a country may be specified
by appending a dash (-) and the state/city code to the country.
The order in this array needs to match that in the series data array.You can use the map function to assist in creating map options.
Since 1.4.0 - moved to the jquery.gchart.ext.js module. |
mapDefaultColor | string | 'bebebe' | Specify the colour used for regions without associated data.
Requires the jquery.gchart.ext.js module.
See the section on
colour for more details.Since 1.4.0 - moved to the jquery.gchart.ext.js module. |
mapColors | string[] | ['blue', 'red'] | Specify the starting and ending colours, or a gradient of colours, for coloured
regions on a map. Requires the jquery.gchart.ext.js module.
Colours are calculated between these end points based on the
data value for each region relative to the maximum for the chart.Since 1.3.0 - colour gradient. Since 1.4.0 - moved to the jquery.gchart.ext.js module. |
qrECLevel | string | null | Specify the error correction level to use for a
QR code
('low' (default), 'medium', 'quarter', 'high').
Requires the jquery.gchart.ext.js module.Since 1.4.0 - moved to the jquery.gchart.ext.js module. |
qrMargin | number | null | Specify the margin (squares) to leave around the outside of a QR code.
The default is 4. Requires the jquery.gchart.ext.js module.Since 1.4.0 - moved to the jquery.gchart.ext.js module. |
onLoad | function | null | Provide a callback function that is invoked when the chart
has been loaded. There are no parameters unless
provideJSON is true , while this
refers to the surrounding division.Since 1.2.3. |
provideJSON | boolean | false | When true invoking the onLoad
callback also passes a JSON
description of the chart as a parameter. This description identifies
the various regions within the chart and can be used to
provide imagemap-like capabilities for it. Use the built-in
findRegion
function to convert from a mouse position into a chart region.
Since 1.3.1. |