jQuery plugin for creating line, bar and candlestick charts.
JavaScript CSS
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
css
js
LICENSE
README.md
examples.html

README.md

jqCandlestick

jQuery plugin for creating line, bar and candlestick charts.

Supported browsers

Should work in all browsers that support the canvas element (tested in newest versions of Chrome, Firefox and Internet Explorer).

Support for Internet Explorer 8 and below should be possible using polyfill and an older version of jQuery. See https://code.google.com/p/explorercanvas for polyfill.

Todo

  • Support for non-date x-axis
  • Update data dynamically
  • Fix x-axis

Usage

Include jQuery, jqCandlestick JavaScript and jqCandlestick CSS:

<script type="text/javascript" src="js/jquery.min.js"></script>
<script type="text/javascript" src="js/jquery.jqcandlestick.min.js"></script>
<link rel="stylesheet" type="text/css" href="css/jqcandlestick.css" />

It is important that you include jQuery before jqCandlestick.

Create a container for your chart and use the jqCandlestick() function on it to create the chart:

<div id="my-chart" style="width: 640px; height: 480px;"></div>

<script type="text/javascript">
  $(function() {
    var data = [/* ... */];
    $('#my-chart').jqCandlestick({
      data: data,
    });
  });
</script>

Where data should be a variable containing a multi-dimensional array of data. The expected format of the data-array depends on the number of data series in the chart. The first element of each row is the x-value (as a UNIX timestamp) (this can be changed in the options).

Many configuration options are available. The default options are defined in $.fn.jqCandlestick.defaults.

Data series

Multiple data series can be defined for a chart:

<script type="text/javascript">
  $(function() {
    $('#my-chart').jqCandlestick({
      data: data,
      series: [{
        type: 'line',
        name: 'Series #1',
      }, {
        type: 'point',
        name: 'Series #2',
        dataOffset: 2
      }],
    });
  });
</script>

Each series inherits its settings from $.fn.jqCandlestick.defaults.seriesDefaults, which is defined as:

seriesDefaults: {
  type: 'point',
  name: null,
  names: [],
  dataOffset: 1,
  yAxis: 0,
  color: '#fff',
}

Four built-in types are available (defined in $.fn.jqCandlestick.types): 'point', 'line', 'column' and 'candlestick'. The name-option defines the name of the series (shown when hovering over the chart) while the names-option, which is only used by type 'candlestick', defines the labels for "open", "high", "low" and "close". The dataOffset-option defines at which offset the values for the series start. The default is 1 which means that a default point-chart will expect a data-array of the format:

[
  [1391697000000, 23], // timestamp, value (offsets 0 and 1)
  [1391696100000, 14],
  [1391695200000, 5],
  // etc...
]

The 'candlestick' type is a bit different, in that it expects 4 values at the offset, e.g. with dataOffset: 1:

[
  [1391697000000, 23, 25, 12, 20], // timestamp, open, high, low, close (offsets 0, 1, 2, 3, 4)
  [1391696100000, 20, 21, 10, 14],
  [1391695200000, 14, 20, 5, 7],
  // etc...
]

The yAxis-option specifies which y-axis to use (if multiple y-axes are defined, as explained in a later section).

The x-axis

The xaxis-option can be used to customize the format of the x-axis:

xAxis: {
  name: 'DATE',
  months: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
  dataOffset: 0,
  // ...
  labels: {
    // ...
    format: 'date',
  },
}

The name-option is used to set the name of the axis while the months-option defines a list of months (for translation-purposes). As with data series, the dataOffset-option specifies the location of x-values in the data array. The default format for the x-axis is 'date', which is currently the only supported value.

Y-axes

Several y-axes can be defined in the yAxis-option, e.g.:

yAxis: [{
  height: 3,
}, {
  height: 2,
  format: { fixed: 2 },
}]

The above example will result in two chart-areas within the chart sharing the same x-axis. The height of the first area will be 60% (3/5) of the total height, while the height of the second area will be 40% (2/5) of the total height.

Each y-axis inherits its options from $.fn.jqCandlestick.defaults.yAxisDefaults which contains the following:

yAxisDefaults: {
  height: 1,
  // ...
  labels: {
    // ...
    format: null, // possible values: a function(x) or an object {fixed: y) where y is number of decimals
  },
}

The height-option defines the height of the axis as the numerator of the fraction height / total_height where the total height is the sum of all height-options. E.g. in the above example the total height is 3 + 2 = 5.

The format of the labels of the y-axis can be defined using the labels.format-option. The default is null which means that the raw numbers will be printed. It is possible to print the number with a specific number of decimals by setting format: { fixed: n }, where n is the number of decimals. It is also possible to define a custom formatting function such as format: function(x) { return Math.round(x); }.

Appearance

There are two built-in themes available: 'light' and 'dark', optimized for white and black backgrounds respectively. The built-in themes are defined in $.fn.jqCandlestick.themes. Colors, fonts and spacings can also be changed manually. The following options are available for customizing the appearance of charts:

{
  theme: 'light', // imports default colors from a theme defined in $.fn.jqCandlestick.themes
  font: '8pt sans-serif', // default font for all text
  padding: { // distances between the boundaries of the chart-container and the chart itself
    top: 0,
    left: 10,
    bottom: 0,
    right: 0,
  },
  plot: {
    spacing: 5, // vertical space between chart areas
    padding: { // distances between plot area and axes
      top: 0,
      left: 15,
      bottom: 0,
      right: 15,
    },
  },
  xAxis: {
    color: '#333', // color of x-axis
    strokeWidth: 1.0, // width x-axis
    tickSize: 5, // length of each tick (can be negative)
    labels: {
      font: null, // font to use for labels
      color: '#999', // color for labels
    },
  },
  yAxisDefaults: {
    color: '#222', // default color of y-axes
    strokeWidth: 1.0, // default width of y-axes
    tickDistance: 40, // minimum distance between ticks
    labels: {
      font: null, // font for labels
      color: '#999', // color for labels
    },
  },
  seriesDefaults: {
    color: '#fff', // default color for series
  },
  info: {
    color: '#999', // color for info
    font: null, // font
    spacing: 20, // distance between values
    position: 'left', // 'left', 'right' or 'auto'
    wrap: 'auto', // 'auto', 'yes' or 'no'
  },
  cross: {
    color: 'rgba(255, 255, 255, 0.5)', // color of cursor-cross
    strokeWidth: 1.0, // width cursor-cross lines
    text: {
      background: '#000', // background color for text
      font: null, // font for text
      color: '#999', // color for text
    },
  },
  containerClass: 'jqcandlestick-container', // class for chart container
  chartCanvasAttrs: { // additional attributes to add to chart canvas element
    class: 'jqcandlestick-canvas',
  },
  crossCanvasAttrs: { // additional attributes to add to cross canvas element
    class: 'jqcandlestick-canvas',
  },
}

Each series type has additional options available:

Point charts

Series with type: 'point' has the following additional options:

{
  radius: 3, // Radius of points
  stroke: null, // Color of stroke (null for no stroke)
  strokeWidth: 2.0, // Width of stroke
}

Line charts

Series with type: 'line' has the following additional options:

{
  strokeWidth: 2.0, // Width of line
}

Bar/column charts

Series with type: 'column' has the following additional options:

{
  width: 5, // Width of each bar/column
  stroke: null, // Color of stroke (null for no stroke)
  strokeWidth: 1.0, // Width of stroke
}

Candlestick charts

Series with type: 'candlestick' has the following addtional options:

{
  names: ['OPEN', 'HIGH', 'LOW', 'CLOSE'], // Value names
  width: 5, // Width of each candlestick
  downColor: null, // Color of decreasing candlestick
  downStroke: null, // Stroke color of decreasing candlestick
  downStrokeWidth: 1.0, // Stroke width of decreasing candlestick
  upColor: null, // Color of increasing candlestick
  upStroke: null, // Stroke color of increasing candlestick
  upStrokeWidth: 1.0, // Stroke width of increasing candlestick
}

Advanced usage

Currently jqCandlestick only has support for 4 different types of series. You can manually add custom types to the $.fn.jqCandlestick.types-object. As an example, the 'point'-type is defined as:

point: {
  dataSize: 1, // defines expected number of values in data-array (would be 4 for candlestick)
  radius: 3, // additional options (default values)
  stroke: null, // ...
  strokeWidth: 2.0, // ...
  // The draw function is called in order to draw a data series of this type.
  // It takes the following parameters:
  //   ctx - Canvas context for drawing
  //   settings - The entire settings object
  //   plot - An object containing some information about the plot area, such as:
  //     min, max - minimum and maximum values for plot area
  //     minY, maxY - top and bottom of plot area
  //   series - series settings
  //   data - entire data array
  //   getX - a function, getX(value), that returns the x-value in pixels for a given value
  //   getY - a function, getY(plot, value), that returns the y-value in pxiels for a given plot area and value
  draw: function(ctx, settings, plot, series, data, getX, getY) {
    ctx.fillStyle = series.color;
    ctx.lineWidth = series.strokeWidth;
    // Iterate over each row in the dataset
    data.forEach(function(row) {
      // Find x- and y-values using the provided functions
      var x = getX(row[settings.xAxis.dataOffset]); // x-axis data offset from settings
      var y = getY(plot, row[series.dataOffset]); // series data offset from settings
      ctx.beginPath();
      // Draw circle
      ctx.arc(x, y, series.radius, 0, Math.PI * 2, true);
      ctx.fill();
      // Draw stroke if set
      if (series.stroke) {
        ctx.strokeStyle = series.stroke;
        ctx.lineWidth = series.strokeWidth;
        ctx.stroke();
      }
    });
  },
},