TeeChart for JavaScript and HTML5

From Steema Software Reference Wiki
Revision as of 13:49, 13 June 2014 by Clive (Talk | contribs)

Jump to: navigation, search

TeeCharttm for Javascript

User Guide

Rev. 1.0, March 2012


  1. [#h.5aasyc8efz27 Introduction]
  2. [#h.uo65ckhz2255 The Tee namespace]
  3. [#h.9kdvcpaijarh The Canvas]
  4. [#h.z8hzcw8aygpa Bounds and position]
  5. [#h.ajm83yle9kyv Format]
  6. [#h.wzimsamdqjvo Background]
  7. [#h.x6ai963c0auo Title and Footer]
  8. [#h.w0yogj4s6fau Adding data to series]
  9. [#h.dbxarmn89fbq The Legend]
  10. [#h.9dndi52jbc3h Axes]
  11. [#h.lcg67chm65vm Axes Wall]
  12. [#h.ohnbslgr4xs2 Series]
  13. [#h.bx72e5n6jt6y Series and Colors]
  14. [#h.5hwd8zlu10n6 Zoom and Scroll]
  15. [#h.fr09v96kok89 Exporting a Chart]
  16. [#h.lujew5980kvc Charting Tools]
  17. [#h.4lem8wtepfp1 Acknowledgements]


This document explains in detail how to create charts and graphs using the TeeChart for Javascript library.

Adding charts to your web pages or applications is fun and easy, see the one-minute for Javascript Getting Started Guide.html Starting Guide, play with the Online Demos or discover the full TeeChart API Reference.

Compared with other programming environments (Java, .NET, Delphi VCL / FireMonkey, etc), the TeeChart Javascript api implements an essential subset of features in order to minimize both the script size and coding complexity.

Current script sizes are 64KB (minified) and 13KB (gzipped)

The Tee namespace

Full code is wrapped around a single €œTee€ identifier (namespace) to avoid cluttering the browser Window global space.  Several €œclasses€ in an object-oriented manner exist Inside the Tee namespace, being Tee.Chart the main class that defines a chart.

The Canvas

Charts are displayed by default using HTML5 Canvas elements. The main class €œTee.Chart€ should be initialized passing the <canvas> element or its id as string:

<canvas id="canvas1" width="300" height="200"></canvas>

Using the canvas id:

var Chart1=new Tee.Chart("canvas1");


Or using the element:

var Chart1=new Tee.Chart(document.getElementById("canvas1"));

Hidden charts can be created without passing any canvas parameter:

var Chart1=new Tee.Chart();


Charts are rendered to canvas when calling the draw method:


Bounds and position

The default xy position of charts inside canvas is 0,0  (left-top corner), and the default size is the same as the associated canvas.

You can override them by changing the chart bounds property:





Most objects (like Series, Annotations and chart sub-objects) include a €œformat€ property to

group all visual attributes in a common place.

The Format class provides the following properties:

fill:  A color in css string format, for example:  #123456,  rgb(255,0,0),   rgba(0,255,0,0.5),  €œblue€

Chart1.panel.format.fill = €œblue€;

round:  Amount in pixels of roundness of rectangle corners (x: horizontal, y: vertical)

Chart1.panel.format.round = { x:10, y:10 }

Chart1.legend.format.round.y = 5;

transparency:  Amount of semi-glass effect, from 0 to 1. (default is zero)

Chart1.legend.format.transparency = 0.5;

shadow: Properties to control drop-shadow visibility behind filled shapes or stroked lines.

   var s = Chart1.panel.format.shadow;

   s.visible = true;

   s.width = 4;        // can be negative for left-side shadow

   s.height = 4;     // can be negative for top-side shadow

   s.blur = 5;

   s.color = €œsilver€;

gradient:  Attributes to fill shapes using a gradient of colors:

  var g = Chart1.panel.format.gradient;

  g.visible = true;

  g.colors = [ €œred€, €œyellow€, €œgreen€ ];  // array of colors

  g.stops = [ 0, 0.1, 1 ];   //  percentages from 0 to 1 for each color (default is null, automatic)

  // €œbottomtop€, €œleftright€, €œrightleft€, €œradial€, €œdiagonalup€, €œdiagonaldown€

  g.direction = €œtopbottom€;  

stroke: Attributes used to draw lines and outlines around filled shapes:

    var s = Chart1.panel.format.stroke;

    s.fill = €œblack€;

    s.size = 4;             // line thickness

    s.join = €œround€;    // segment joins (€œround€, €œmiter€, €œbevel€ )

    s.cap = €œsquare€;   // ending line terminators (€œsquare€, €œbutt€, €œround€ )

    s.dash = [ 5,10 ];   // dot-dash... array of pixels (default is null to draw solid lines)

    s.gradient.visible = true;   // gradient object with colors, direction, etc

font:  Properties to display text:

   var f = Chart1.title.format.font;

   f.style = €œ22px Verdana€;     // or: €œbold italic 14px Tahoma€, etc, etc

   f.fill = €œblue€;

   f.shadow.visible = true;    // text drop-shadow

   f.stroke.fill = €œwhite€;        // draws an outline around text

   f.gradient.visible = true;   // fills text with gradient instead of using font.fill

   f.textAlign = €œcenter€;    // horizontal alignment: €œstart€, €œend€, €œleft€, €œcenter€, €œright€

   // vertical alignment: €œtop€, €œmiddle€, €œbottom€, €œalphabetic€, €œhanging€, €œideographic€

   f.baseLine = €œtop€;   


The chart background appearance is controlled by the €œpanel€ sub-object:

Chart1.panel.transparent = false;

The panel property includes a format subproperty to control background€™s appearance:

Chart1.panel.format.gradient.visible = true;


€¦ etc

Title and Footer

These two chart properties are used to display text at chart top and bottom sides:

Chart1.title.text = €œHello€;

Chart1.footer.text = €œWorld€;

Multiple-line text is done by adding €œ\n€ line-feed delimiters:

Chart1.title.text = €œHello \n World€;

Title and Footer are Annotation-derived objects, and such they inherit the €œformat€ sub-properties:

Chart1.title.visible = true;

Chart1.title.transparent = false;

Chart1.title.format.gradient.visible = true;


Adding data to series

Data is added to a chart using €œSeries€ objects.

Multiple series can exist in the same chart. Each series can be of a different type (line, area, bar, pie, etc) so you can mix several styles altogether.

Direct data:

The simplest way to add data to a chart is by passing an array of values at chart construction time:

var Chart1=new Tee.Chart("canvas1", [ 5,6,2,9,1] );

This creates a new series object of type Tee.Bar by default, and assigns the array to series.data.values property.

Multiple series are created when passing a multi-dimensional array:

var Chart1=new Tee.Chart("canvas1", [ [ 5,6,2,9,1], [ 8,4,3,7,5] ] );

The default series style Tee.Bar can be changed passing a type parameter:

var Chart1=new Tee.Chart("canvas1", [ [ 5,6,2,9,1], [ 8,4,3,7,5] ] , Tee.Area);

Creating series:

Series are manually added into a chart using the addSeries method:

var bar =Chart1.addSeries(new Tee.Bar());

Series have a default €œtitle€ string property that is used at chart legend.

When series are added to a chart, title is assigned to €œSeries€ plus the series index in the Chart1.series.items array (€œSeries1€, €œSeries2€ and so on).

You can override the default title:

bar.title = €œMy Data€;

By default series are empty, they contain no data.

For testing purposes its handy to add random values, for example:

Chart1.addSeries(new Tee.Line()).addRandom(1000);  // Thousand random points

Data can be specified inline when creating the series:

Chart1.addSeries(new Tee.Pie( [ 10, 20, 30, 40 ] ));

All data is stored under the series €œdata€ property arrays.

You can access and modify data directly:

var a = new Tee.Area();

Chart1.addSeries( a );

a.data.values =  [ 10, 20, 30, 40 ];

Each series point has an associated text label. By default labels are empty, you can modify them using the data.labels property:

a.data.labels =  [ €œa€, €œb€, €œc€, €œd€ ];

Some series allow specifying point positions or other point parameters.

For example, Line and PointXY series can optionally display each line segment or point at a specific €œX€ axis coordinate:

var p = new Tee.PointXY();

p.data.values = [5, 7, 9];

p.data.x = [0.23, 14, 16];


Other series like Bubble have a €œdata.radius€ array, and Candle series have data.open, data.close, data.high and data.low arrays.

Adding data from other sources

Several helper functions are provided in a separate script (teechart-table.js) to import data from different sources (see the online demos for details), for example:

From a textarea html element:

Chart1.addSeries(new Tee.Bar(document.getElementById("data")) );

<textarea id="data" rows="20" cols="20" wrap="off">

From a table html element:

Chart1.fromTable('table1', Tee.Bar, true, 0,0);

<table id=€table1€>...</table>

From a text file URL:

// Warning: data file url should be at €œsame domain origin€

Chart1.addSeries(new Tee.Bar(€œhttp://myweb.com/mydata.txt€));

From another series in same or different chart:

// Simply assign the €œdata€ property from one series to another:

Chart1.series.items[0].data = Chart2.series.items[3].data;

From xml formatted text:

 var b=Chart1.addSeries(new Tee.Bar());

<textarea id="xml" rows="10" cols="60" "wrap="off">
<series name="Friends" color="Blue" metric="Quantity">
 <point name="Facebook" value="123"/>
 <point name="Twitter" value="456"/>
 <point name="Google " value="789"/>

From JSON formatted text:

var b=Chart1.addSeries(new Tee.Bar());

The Legend

The indicator where series names and series points are displayed is called the legend.

Several properties can be used to customize the legend behaviour and appearance.

Chart1.legend.visible = true;

Chart1.legend.transparent = false;

Chart1.legend.format.fill = €œyellow€;

Legend position and orientation:

Chart1.legend.position = €œleft€;  // €œtop€, €œbottom€, €œright€

Chart1.legend.inverted = false;    // draws items in normal order

Select what to display at legend:

Chart1.legend.legendStyle = €œvalues€;   // €œauto€, €œseries€, €œvalues€

Chart1.legend.textStyle = €œpercentlabel€;    // show point value as percent, and point text label

Font and formatting:

Chart1.legend.format.font.style = €œ20px Arial€;

Margins to chart top and chart axes:

// distance from chart edge, percentage from 0 to 100 ( 0 means automatic )

Chart1.legend.align = 0; 

// distance from legend to axes

Chart1.legend.padding = 5;   //  in pixels

Title text on top of items:

Chart1.legend.title.text = €œMy Legend€;

Chart1.legend.title.visible = true;

Symbols next to legend items:

Chart1.legend.symbol.visible = true;

Chart1.legend.symbol.width = 20;

Chart1.legend.symbol.format.shadow.width = 5;

Other legend properties:

Chart1.legend.fontColor = true;  // each item text is painted using its point or series color

Chart1.dividing.fill = €œblue€;   // draws lines between legend items


Most Series data are displayed using axes to convert from data values to canvas pixel coordinates.  Some series like Pie and Donut do not use axes.

There exist four default axes inside a chart:  left, top, right and bottom.

var a = Chart1.axes.left;

Each series has two properties that control which horizontal and vertical axes are used.

By default, the horizontal axis is €œbottom€, and the vertical axis is €œleft€.

Chart1.series.items[0].horizAxis = €œtop€;

Chart1.getSeries(1).vertAxis = €œright€;

Series can also display using both axes:

Chart1.series.items[2].horizAxis = €œboth€;

Axis visibility is controlled globally by the Chart1.axes.visible property, and individually using the axis visible:

Chart1.axes.visible = true;

Chart1.axes.bottom.visible = true;

Scales are automatically controlled by default. Each axis calculates its minimum and maximum values based on its associated series values and visual properties.

You can override axis automatic scales and set them manually:

var a = Chart1.axes.left;

a.automatic = false;

a.minimum = 50;

a.maximum = 200;

The above code is equivalent to:

Chart1.axes.left.setMinMax( 50, 200 );

Logarithmic scales

Axes scales are linear by default. The log property determines the axis to use natural logarithm scaling instead of linear:

Chart1.axes.left.log = true;

Axis Labelling

Each axis automatically calculates the €œbest€ distance from labels, using labels formatting properties like font.size.  Custom labels can be controlled changing the axis increment property:

Chart1.axes.bottom.increment = 100;   // one label at each 100 values in axis scale.

Increment is zero by default, meaning automatic calculation.

Labels can display series values or series point labels. This is controlled with the labelStyle property:

// options are:  €œauto€, €œnone€, €œvalue€, €œmark€, €œtext€, €œx€

Chart1.axes.left.labels.labelStyle = €œtext€;

When series contain date-time values, labels are formatted according to dateFormat property using Steven Levithan <stevenlevithan.com> date.format.js library.

Chart1.series.items[0].data.x = [ new Date() ];

Chart1.axes.bottom.labels.dateFormat = €œshortDate€;

Other properties that control labels:

Chart1.axes.left.labels.alternate = true;  // double quantity of labels

Chart1.axes.right.labels.visible = false;  // show or hide labels

Chart1.axes.left.labels.decimals = 3;    // output numbers with up to 3 fixed decimals

Chart1.axes.bottom.labels.rotation = 90;    // 90 degree rotation

Axis Grids

The axis grid property includes a format to draw grid lines that go across chart axes space.

Chart1.axes.left.grid.visible = true;

When grid fill color is not empty, grids are filled alternatively as €œbands€:

Chart1.axes.left.grid.format.fill = €œred€;

Grid lines format is controlled by stroke property:

Chart1.axes.left.grid.format.stroke.size = 5;

Default grid lines are solid lines. The lineDash property displays dash-dot grids:

Chart1.axes.left.grid.lineDash = true;

On browsers that natively support canvas dash strokes, the above code is equivalent to:

Chart1.axes.left.grid.format.stroke.dash = [10,5];   // see €œdash€ stroke property

Axis Ticks

Axis include ticks an innerTicks properties of type €œTicks€, that have a stroke property.

Ticks are drawn from labels to axis. Inner ticks display from axis towards inside.

Chart1.axes.bottom.innerTicks.visible = true;

Chart1.axes.left.ticks.length = 9;

Chart1.axes.top.ticks.stroke.fill = €œblue€;

Minor Ticks

From tick to tick, the minorTicks axis property can be used to display small sub-ticks:

Chart1.axes.left.minorTicks.visible = true;

Chart1.axes.left.minorTicks.length = 2;

Chart1.axes.left.minorTicks.count = 5;

Chart1.axes.left.minorTicks.stroke.fill = €œgreen€;

Axis Title

Close to an axis, the title property is used to display text that identifies the axis:

Chart1.axes.bottom.title.text = €œQuantity€;

Chart1.axes.bottom.title.text.format.font.fill = €œred€;

Axis positioning

Size and position of axes is automatic by default.

The axis startPos and endPos properties control the pixel coordinate of axes.

Axes Wall

The rectangular space where axes are painted is called €œthe back wall€.

Formatting is provided using the walls.back property:

Chart1.walls.back.visible = true;

Chart1.walls.back.transparent = false;

Chart1.walls.back.format.gradient.visible = true;


Inheriting from a common Series class, several charting styles are provided, each as a different object class with its own properties and methods.

  1. Line
  2. Bar  / Horizontal Bar
  3. Area / Horizontal Area
  4. PointXY (scatter)
  5. Pie
  6. Donut
  7. Bubble
  8. Candle (financial OHLC)

Series Marks

The marks property displays text annotations near series points:

var s = new Tee.Bar();

s.marks.visible = true;

s.marks.style = €œpercent€;

Series and Colors

Charts have a palette property (an array [ ] of colors in string format).

This palette is used by series to paint its points, and by chart legend to display series items symbols.

Chart1.palette = [ €œred€, €œblue€, €œgreen€, €œyellow€ ];

Colors in the palette are reused in a circular way when more series or more points in a series exist than the size of the palette.

Series also contain a palette of colors to override the chart palette. By default is a €œnull€ empty array so they share the chart palette.

Zoom and Scroll

Charts can be zoomed and scrolled by manual code or mouse / touch events.

Default behaviour is to drag the right mouse button inside axes to scroll, and drag a rectangle using the left mouse button to zoom / unzoom (zoom dragging to bottom-right direction, and unzoom dragging to left-top direction).

This can be overridden using the chart zoom and scroll properties:

Chart1.zoom.enabled = true;

Chart1.zoom.mouseButton = 0;   // 0=left button, 1=middle, 2=right button

Chart1.zoom.stroke.fill = €œyellow€;

Chart1.scroll.enabled = true;

Chart1.scroll.mouseButton = 2;

Chart1.scroll.direction = €œhorizontal€;  // can be: €œvertical€ or €œboth€

The chart onzoom event is triggered when the user releases the mouse button after the chart is zoomed.

The chart onscroll event is triggered while the user is scrolling the chart by dragging it.

Exporting a Chart

To obtain a PNG or JPEG image from a chart, you can use the canvas toDataURL method, or the included toImage function:

Chart1.toImage( €œimg€ );   // fills <img id=€img€> element with chart as PNG image.

Chart1.toImage( €œimg€ , €œjpg€, 90 );   // fills image with a jpeg image with 90% compression

Charting Tools

Some features are implemented as a €œtool€ objects.  These objects can be added to a chart tools array property to activate them.


Custom text can be displayed at any chart position using annotation tools:

Chart1.tools.add( new Tee.Annotation( Chart1, €œHello€, 50, 50 ) );

The annotation object has a format, text and position properties.

Annotations can also act as buttons when using the onclick event:

var  b1=new Tee.Annotation(Chart1, €œbutton 1€, 100, 100);


b1.onclick=function(button,x,y) { alert("Clicked button 1"); }

Chart1.tools.add( b1 );


This tool displays series data when moving the mouse over series data point.

var  tip=new Tee.ToolTip(Chart1);

tip.format.font.style="16px Tahoma";


The ToolTip tool provides onshow, onhide and ongettext events.


Draggable cursor lines are implemented as a tool object:

  var t=new Tee.CursorTool(Chart1);




The cursor tool includes a direction property (to display cursor as an horizontal line, vertical or both) and an onchange event that is triggered when the cursor is dragged.

Dragging Points

The DragTool implements mouse / touch point dragging.

  Chart1.tools.add(new Tee.DragTool(Chart1));

Includes onchanging and onchanged events.

The target property determines which series and which series point index is being dragged.


A generic slider control that can be used inside a chart to change any value.

 var slider=new Tee.Slider(Chart1);










  slider.onChanging=function(slider,value) {

    Chart1.title.format.font.style = value.toFixed(0) €œ Verdana€;

    return value;




The scroller tool displays a simplified view of another chart and allows scrolling it.

Please refer to this demo for a complete example.

Series Animations

Simple animations performed by changing axis scales or rotating transformations:

  var a=new Tee.SeriesAnimation(Chart1);

  a.duration=500; // milliseconds


The animate method to start the animation can be called for example from an html button:

<BUTTON type="button" onclick="Chart1.tools.items[0].animate();">Animate</BUTTON>


The following are libraries and code snippets that have been used to develop TeeChart for Javascript:

date.format.js by Steven Levithan

Used by chart axes to format date-time string labels from series data. (See axis dateFormat property).

splines Copyright 2010 by Robin W. Spencer

Custom modified code to draw smooth curves between series points (Line, Area, etc).

JQuery.js, JSON and Three.js are technologies used in TeeChart online demos that are optional (not required by TeeChart).