tl;d3

tld3.js is a lightweight library that makes building d3.js graphs much simpler. It abstracts the intricacies of d3.js while harnessing the power of its data-driven DOM manipulation.

Table of Contents

1. Usage
2. Requirements
   1. Installing Dependencies
3. The Basic Idea
4. Why use tld3.js?
5. What is tld3.js not good for?
6. Chart types
7. Roadmap
8. Contributing

Usage

Check out our docs to get started!

Requirements

• The latest version of D3.js: Releases

Installation

To install:

npm install --save tld3

This assumes that you’re using npm package manager. With npm, you can either use a module bundler like Webpack or Browserify to consume CommonJS modules, or if you don't prefer to use a module bundler, you can use ES6 to import tld3.js into your project file(s).

If you aren't using npm or a modern module bundler, you can use a pre-built version from cdnjs and place the src link in script tags in your html file(s). This will make tld3.js available as a global object in your project.

Idea

tl;dr: Creating a bar chart in tld3.js is as simple as:

Example 1: Using raw JSON data

const data = [
              	{	"letter":"A",
              		"frequency":".08167"
              	},
              	{	"letter":"B",
              		"frequency":".01492"
              	},
              	{	"letter":"C",
              		"frequency":".02782"
              	},
              	{	"letter":"D",
              		"frequency":".04253"
              	},
                // ... etc
              ];

// tl;dr :)
tld3.make('BarChart')
    .using(data)
    .in('#barchart');

Example 2: Using CSV file

tld3.upload('./data/scatterData.csv') // uploading csv data from a file
    .then((data) => {
      tld3.make('ScatterChart')
          .using(data)
          .in('#scatterchart');
    })
    .catch((err) => {
      console.error(err);
    });

Example 3: Using Firebase database url

tld3.uploadFirebase('https://tld3.firebaseio.com/') // upload data from from Firebase database
    .then((data) => { // if the promise returns successfully, create the chart
      tld3.make('LineChart')
          .using(data)
          .in('#linechart');
    })
    .catch((err) => { // else handle error
      console.error(err);
    });

We support data in many formats, including raw JSON or importing data from csv, tsv or JSON files. We now also support Firebase database urls which allows you to have live data updates!

See the docs for more information.

Why

• Powerful: tld3.js rides on d3.js's powerful visualization and data-driven DOM manipulation capabilities
• Easy-to-use: tld3.js offers an extremely simple and expressive syntax
• Flexible: tld3.js is flexible enough to work with several different data formats, including csv, tsv, JSON and even Firebase!
• Customizable: The API offers various ways to customize the charts to best suit your needs
• Minimal API surface area: tld3.js only requires that you learn a handful of methods before you're on your way to making beautiful graphs
• tl;dr: Tooltips and transitions automagically included!

WhyNot

• Complex physics based d3.js components or animations
• Brushing, zooming and filtering of selections using built in stateful d3 tools
• Anything that requires a lot of DOM mutation, events, timers or internal state

Types

We currently support the following types of charts:

• Bar chart
• Left bar chart
• Line chart
• Multi-line chart
• Area chart
• Scatter chart
• Donut chart

Roadmap

View the project roadmap here

Contributing

See CONTRIBUTING.md for contribution guidelines.

Team

• Product Owner: Preethi Kasireddy
• Scrum Master: Banun Atina Idris
• Core Contributors: Colin Seale, Preethi Kasireddy, Banun Atina Idris