Repository files navigation

Paths.js is a library to generateSVG paths, allowing you to create your own charts using a functional and testable API. It provides the primitives to create various shapes and charts starting from raw data, but it does not prescribe how you render these charts. This means you can use Paths.js to build components for your favorite frontend framework, and works even server-side onNodeJS.

Paths.js offers three APIs, of increasing abstraction. The lowest level is a chainable API to generate an arbitrary SVG path. On top of this, paths for simple geometric shapes such as polygons or circle sectors are defined. At the highest level, there is an API to generate some simple graphs (pie, line chart, radar...) for a collection of data, assembling the simple shapes.

Latest version is0.4.6 - seethis for the necessary changes from0.3.5.

• Demos
• Philosophy
• Documentation
• Resources
• Browser support
• Migration to 0.4
• Using Paths.js with the Canvas API
• Using Paths.js with Scala.js
• Contributing

Of course, when judging a chart library, the first request is to have a look at results. But Paths.js is different: it provides the geometry, and you draw the charts.

That said, we have two demos. Thefirst one is written using React (source here).

Theold demo is written using Ractive (source here).

Drawing beautiful charts is a craft, and often one needs to add custom interactions, styling or animations. There are some beautiful chart libraries out there, such asFlotcharts orDimple, and if those are enough for your needs, they can be a pleasure to use.

In many cases, though, what I really wanted was a library to take care of the generation of the chart, while still leaving me the possibility to render the actual thing. Paths.js does exactly this. It eventually generatesSVG paths with a high level API. These paths can be then used together with a template engine such asMustache orHandlebars to display SVG graphics in the browser. If instead of a static template engine, you use a data binding library, such asFacebook React,Ractive.js orAngular, you get animated graphics for free.

In designing Paths.js, I have tried to follow a few principles:

• paths should be immutable
• all exposed methods should be pure
• from this follows that it is trivial to test components
• and that they work on Node.js as well
• it should be easy to integrate Paths.js into various frameworks

A detailed documentation is available on thewiki. Here are links to the main entry points.

Paths.js offers three APIs, of increasing abstraction. The lowest level is a chainable API to generate an arbitrary SVG path. On top of this, paths for simple geometric shapes such as polygons or circle sectors are defined. At the highest level, there is an API to generate some simple graphs (pie, line chart, radar...) for a collection of data, assembling the simple shapes.

• Installation and usage
• Low level API
• Mid level API (shapes)
• High level API (graphs)
• Miscellaneous

Those users who prefer explicit typed interfaces canbrowse the API of the Scala.js bindings.

These resources give a more detailed exposition of the philosophy behind Paths.js:

• Reactive SVG charts with Ractive.js and Paths.js by Marcello La Rocca
• My talk at MilanoJS user group, together with theexamples
• Reactive SVG charts with Ractive.js
• Visualization is for Sharing: Using React for Portable Data Visualization by Nate Hunzaker
• How to Create Performant, Template-based Charts with Paths.js

Paths.js works in any environment that supports a modern version of Javascript, namely ES5. This includes any version of Node.js and all recent browsers. If you need support for older browsers, you can include anES5 polyfill.

On the other hand, not every browser will be able to display the SVG graphics that you will generate. Usually, recent desktop browsers are ok, but mobile browser are slow in adopting the SVG specification. You can refer tocaniuse for more detailed information.

Version 0.4 was rewritten in ES6 instead of CoffeeScript for future-proofing. The currently published version is0.4.0.

A few API changes were introduced, namely all keys are now camel cased.

In particular:

• in the low-level verbose API,large_arc_flag has been renamed tolargeArcFlag, andsweep_flag tosweepFlag
• the rectangle width in the Sankey diagram, is now calledrectWidth instead ofrect_width

Also, the default for thegutter parameter is now10 everywhere (that is, also in theBar andWaterfall charts).

Everything else should be the same, so if you find any regression, please open a issue.

Paths.js does not directly support thecanvas element, essentially because there is no need to do so. Thecanvg project allows to draw SVG paths on a<canvas> element, and it seems that canvaswill be able to support SVG paths natively. Of course, canvas-based solutions limit the possibilities offered by data binding libraries for interaction, but they could be used as a fallback on less recent browsers.

It is possible to use Paths.js withScala.js -this library defines the bindings.

Contributions to Paths.js are always welcome! Seethis wiki page for suggestions and guidelines.