NASDAQ: 2873.54 (close 3/18-4/29)

DOW: 12810.54 (close 3/18-4/29)

SF Giants: Last game 11/1

jQuery Sparklines

About

30 Nov 2010
Version 1.6 Released

Come work at Splunk!

Only amazing UI engineers
should mouse over here ;-)

Come work at Splunk!

If you love working with cutting edge web technologies, my colleagues and I would love to have you on our team at Splunk in San Francisco.

We're actively looking for talented engineers who have lots of experience with HTML, CSS, JavaScript, HTTP, REST, AJAX, Python/Ruby/etc and the whole web stack to help build the next generation UI for our award winning product (Download it; give it a try! )

If that sounds like you, drop me an email (no agents) with your resume and an idea of the great stuff you've done with the web, or check out our careers page where we have lots of other opportunities listed too.

Look forward to hearing from you!
Gareth

This jQuery plugin generates sparklines (small inline charts) directly in the browser using data supplied either inline in the HTML, or via javascript.

The plugin is compatible with most modern browsers and has been tested with Firefox 2+, Safari 3+, Opera 9, Google Chrome and Internet Explorer 6, 7 & 8.

Each example displayed below takes just 1 line of HTML or javascript to generate.

The plugin was written by Gareth Watts for Splunk Inc and released under the New BSD License.

Examples

Pie charts

Bullet charts



Try It Out

  • Chart type:
  • Values:
  • Height: (css units; try 50px for pixels
  • Width: or 2em for double the font size)
  • Line Colour:
  • Fill Colour:
  • Spot Colour:
  • Spot Size: (in pixels)
  • Line Width: (in pixels)

Mouse speed

Inline line graphs

Bar charts negative values:

Composite inline

Inline with normal range

Composite bar

Discrete
Discrete with threshold

Customize size and colours

Tristate charts
(think games won, lost or drawn)

Tristate chart using a colour map:

Box Plot:
Pre-computed box plot

News

30 November 2010 - Version 1.6 Released
This release primarily makes it easier to work with the sparklines if your environment requires you to pass options such as colours, etc on the tags themselves, rather than feeding them to the sparkline function. It also allows for values to passed as an attribute on the tag, as well as a comment inside the tag. This avoids the values being displayed on screen briefly before the sparkline function has a chance to execute.

eg.

<span class="sparkline" sparkType="bar" sparkBarColor="green"><!-- 1,2,3,4 --></span>

$('.sparkline').sparkline('html', { enableTagOptions: true });
        

This release also:

See the changelog for the complete list of changes.


1 March 2010 - Version 1.5.1 Released
I accidently left a stray comma in the 1.5 release which breaks compatibility with Internet Explorer. This version contains only a fix for that bug.

26 February 2010 - Version 1.5 Released
This version contains a number of minor updates and fixes, including:

See the changelog for the complete list of changes.


14 September 2009 - Version 1.4.3 Released
This version adds support for null values for line and bar charts, updates the default pie chart colours, adds the colorMap option for bar charts and adds a lineWidth option for line charts. - See the changelog for full details.

Over 3,000 people have bookmarked this site on delicious now! Only 7 votes on the jQuery plugins site though; maybe you could help with that ;-)


25 April 2009 - Version 1.4.2 Released
This release just fixes the drawing of circular spots on line charts for Internet Explorer 8.


27 March 2009 - Version 1.4.1 Released
This is a bug fix release - It addresses an off-by-one-pixel error when rendering sparklines in Internet Explorer. It also addresses some issues with sparklines not being rendered in some situations with jQuery 1.3 and higher.


25 February 2009 - Version 1.4 Released
This version adds box plots 4,27,34,52,54,59,61,68,78,82,85,87,91,93,100 suggested by Daniel Kadosh. What's a box plot?.

This release also includes a few bug fixes including one where lines would not always appear crisp in canvas based browsers such as Firefox.

Also at this time IE8 RC1 is out.. It looks like sparklines work fairly well in this release, although the small circles used in line charts, box plots, etc. don't show up.


25 January 2009 - Version 1.3 Released
This version fixes some positioning issues on all platforms and adds some support for Internet Explorer 8. IE 8 beta 2 (the latest beta release) seems to have some VML bugs though that I haven't been able to work around yet, so the results aren't perfect.

This version also adds a new function called $.sparkline_display_visible() - Call this anytime sparklines that were drawn into a non-displayed element may have just become visible so that they will be correctly rendered. For example, this site uses the function to make sure sparklines displayed in the various tabbed pages are drawn when the tab is selected.

Finally I updated the site and docs somewhat as the old layout was looking a little cramped.


21 November 2008 - Version 1.2.1 Released
Fixes a couple of pie chart bugs; no new features.


19 November 2008 - Version 1.2 Released
Some important bug fixes amongst some basic new features:

See the changelog for the complete list of changes.


14 August 2008 - Using Sparklines with Splunk
I gave a quick 5 minute demo at the Splunk Developers Boot Camp on using the Splunk PHP SDK with jquery.sparkline.js to chart the traffic this page received within the first few days of its launch.

Check out the short write up i posted to the new Splunk Wiki for the code and data I used to make it work (it was really easy) and if you download your own free copy of Splunk you can try it yourself ;-)


29 July 2008 - Version 1.1 Released
Thanks for the suggestions for improvements - This version fixes several bugs and adds some more features and chart types including

See the changelog for the complete list of changes.


17 July 2008 - Version 1.0 Released
Initial version released

Documentation

Quick Start

To add some sparklines to your web page you need four things:

  1. The jQuery javascript library loaded into the page - At least version 1.2 or higher
  2. A copy of jquery.sparkline.js loaded into the page which you can download from this site
  3. An inline tag on the page within which to display the sparkline (eg. <span>)
  4. A call to the sparkline() function to actually display the sparkline.

Additionally rendering the page in standards mode (see the DOCTYPE declaration in the example below) maximizes compatibilty with Internet Explorer.

Here's a simple web page that will display some sparklines:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 
    "http://www.w3.org/TR/html4/strict.dtd">
<head>

    <script type="text/javascript" src="jquery-1.4.4.js"></script>
    <script type="text/javascript" src="jquery.sparkline.js"></script>

    <script type="text/javascript">
    $(function() {
        /** This code runs when everything has been loaded on the page */
        /* Inline sparklines take their values from the contents of the tag */
        $('.inlinesparkline').sparkline(); 

        /* Sparklines can also take their values from the first argument 
        passed to the sparkline() function */
        var myvalues = [10,8,5,7,4,4,1];
        $('.dynamicsparkline').sparkline(myvalues);

        /* The second argument gives options such as chart type */
        $('.dynamicbar').sparkline(myvalues, {type: 'bar', barColor: 'green'} );

        /* Use 'html' instead of an array of values to pass options 
        to a sparkline with data in the tag */
        $('.inlinebar').sparkline('html', {type: 'bar', barColor: 'red'} );
    });
    </script>
</head>
<body>

<p>
Inline Sparkline: <span class="inlinesparkline">1,4,4,7,5,9,10</span>.
</p>
<p>
Sparkline with dynamic data: <span class="dynamicsparkline">Loading..</span>
</p>
<p>
Bar chart with dynamic data: <span class="dynamicbar">Loading..</span>
</p>
<p>
Bar chart with inline data: <span class="inlinebar">1,3,4,5,3,5</span>
</p>


</body>
</html>
        

Click here to open this example in a new window.

As the example shows, the values to be used in a sparkline can either be supplied inline, inside the tag to be used as the target or can be passed as the first parameter to the sparkline() function.

To draw different types of charts, or overlay one on top of another, or display charts into hidden layers, read on.

Syntax

$(selector).sparkline(values, options);
        

Values can either be an array of numbers or "html" which causes the values to be read from from the selected tag:

<span class="sparklines">1,2,3,4,5,4,3,2,1</span>
<span id="ticker"">Loading..</span>

$('.sparklines').sparkline('html');
$('#ticker').sparkline([1,2,3,4,5,4,3,2,1]);
        

Values supplied in the tag can also appear inside a comment, or as an attribute of the tag itself:

<span class="sparklines"><!-- 1,2,3,4,5,4,3,2,1 --></span>
<span class="sparklines" values="1,2,3,4,5,4,3,2,1"></span>
        

By default the plugin will look for an attribute called "values" on the tag to find values to render, but you can change this by setting the tagValuesAttribute option. This can be useful if you want to create a composite graph

Options is an object that specifies the type of sparkline to draw, colours to use, etc

$('#barchart').sparkline(myvalues, { type:'bar', barColor:'green' });
        

If necessary, options can be passed as attributes on each tag. This requires setting the enableTagOptions option when calling the sparklines() function and reduces performance somewhat (more critical on IE6)

<span class="sparklines" sparkType="bar" sparkBarColor="green"><!-- 1,2,3,4,3,2,1 --></span>
<span class="sparklines" sparkType="bar" sparkBarColor="red"><!-- 1,2,3,4,3,2,1 --></span>

$('.sparklines').sparkline('html', { enableTagOptions: true });
        

Each option must be prefixed with "spark", though this can be changed by passing a tagOptionPrefix option to the sparkline() function

You can also override the default options for all subsequent sparklines by assigning values to $.fn.sparkline.defaults

Eg. to change the default line color as listed in the common options below, you can do:

$.fn.sparkline.defaults.common.lineColor = 'red';
        

Replace 'common' with 'line', 'bar', 'tristate', 'discrete', 'bullet', 'pie' or 'box' to set options specific to those chart types.

Common Options

Hidden Sparklines

If you try to display a sparkline in a tag that's currently not visible (ie. the tag or one of its parents are set to display:none) then you'll find that the sparkline hasn't been rendered when you finally make the tag visisble. This is because a hidden tag has no size so we can't detect the area to draw on.

The solution is to call the $.sparkline_display_visible() function anytime a sparkline may have become visible so that it can be correctly rendered. This is the technique this site uses to handle the sparklines that are hidden in the different tabbed sections.

Line Chart Options

Line charts are the default chart type, but to specify the type explicitly set an option called "type" to "line".

By default the values supplied to line charts are presumed to be y values mapping on to sequential (integer) x values. If you need to specify both the x and y values for your chart, you have a few options:

  1. Inline: x and y values are separated by a colon: x:y,x:y,x:y - eg. <span class="linechart">1:3,2.7:4,4.8:3</span>
  2. Array of arrays: An array of [x,y] arrays: $('#linechart').sparkline([ [1,3], [2.7,4], [4.8,3] ]);
  3. Separate arrays: Pass x values separately: $('#linechart').sparkline([3,4,3], { xvalues: [1,2.7,4.8]});

You can also specify a value of "null" to omit values from the chart completely. eg:
<span class="linechart">1,2,3,null,3,4,2</span> becomes:

Bar Chart Options





Set the "type" option to "bar" to generate bar charts. Values can be omitted by using the "null" value instead of a number.

Tristate Chart Options

Set the "type" option to "tristate" to generate tristate charts.

Discrete Chart Options

Set the "type" option to "discrete" to generate discrete charts.

Bullet Graph Options

Set the "type" option to "bullet" to generate bullet graphs.

See the wikipedia page for more information on Bullet graphs.
Supplied values must be in this order: target, performance, range1, range2, range3, ...

Pie Chart Options



Set the "type" option to "pie" to generate pie charts.

These little pie charts tend only to be useful with 2 or 3 values at most

Box Plot Options



See the wikipedia page for more information on Box plots

Set the "type" option to "box" to generate box plots.

As noted in the options above, by default "raw" is set to false. This means that you can just pass an arbitrarily long list of values to the sparkline function and the corresponding box plot will be calculated from those values. This is probably the behaviour you want most of the time.

If, on the other hand, you have thousands of values to deal with you may want to pre-compute the points needed for the box plot. In that case, set raw=true and pass in the computed values. If showing outliers, supplied values of:
low_outlier, low_whisker, q1, median, q3, high_whisker, high_outlier
Omit the outliers and set showOutliers to false to omit outlier display.

License

This plugin is copyright Splunk Inc and licensed using the New BSD License

Download

Note: jquery.sparkline.js is a plugin for jQuery - You need to include both on your page to generate sparklines.

NOTE: Be sure to copy the files linked below to your own server - If you embed the plugin as a link from my server, your site will be broken when this site is down (as it occasionally is).

If you use the plugin on a production site I'd love to see it in action, so please send me an email! (be sure to include "jQuery Sparkline" in the subject).

Version 1.6:

Version 1.5.1:

Version 1.4.3:

Version 1.3:

Version 1.2.1:

Who's Using It

Are you using jquery.sparkline on your project or site? Send me a quick email and I'll add a link here! (try to send a link to an example of the plugin in action for bonus points ;-) )

Current users include:

Feedback

Feedback and patches are welcome - Please direct email to Gareth Watts - gareth@splunk.com (be sure to include "jQuery Sparkline" in the subject) or find me on Twitter.