kristw / d3kit-timeline

A simple timeline component that labels do not overlap.

Introduction | Demo | API Reference

d3Kit-timeline

If you want to have a simple timeline that labels do not overlap, but too lazy to implement one from scratch, this library is for you. Below is a screenshot of four timelines of the same data, each can be created via ~10 lines of code. See demo.

The use case of this library is not limited to temporal data. You can change the scale to be d3.scale.linear() or something else to support x-value that is not time.

This small library is built on top of D3, d3Kit and Labella.js.

Note: If you are upgrading from v0.x.x to v1.x.x, this library now return the constructor d3KitTimeline instead of d3Kit. Please see the change logs for more detail.

Install

npm install d3kit-timeline --save

or

bower install d3kit-timeline --save

Example Usage

If you have this dataset

var data = [
  {time: new Date(1977, 4,25), episode: 4, name: 'A New Hope'},
  {time: new Date(1980, 4,17), episode: 5, name: 'The Empire Strikes Back'},
  {time: new Date(1984, 4,25), episode: 6, name: 'Return of the Jedi'},
  {time: new Date(1999, 4,19), episode: 1, name: 'The Phantom Menace'},
  {time: new Date(2002, 4,16), episode: 2, name: 'Attack of the Clones'},
  {time: new Date(2005, 4,19), episode: 3, name: 'Revenge of the Sith'},
  {time: new Date(2015,11,18), episode: 7, name: 'The Force Awakens'},
];

Here is how to create a timeline with labels on the right.

var chart = new d3KitTimeline('#timeline', {
  direction: 'right',
  initialWidth: 400,
  initialHeight: 250,
  textFn: function(d){
    return d.time.getFullYear() + ' - ' + d.name;
  }
});

chart.data(data).resizeToFit();

For more detailed usage please refer to the API Reference.

Import to your project

Choice 1. Global

Adding this library via <script> tag is the simplest way. By doing this, d3KitTimeline is available in the global scope.

<script src="bower_components/d3/d3.min.js"></script>
<script src="bower_components/d3kit/dist/d3kit.min.js"></script>
<script src="bower_components/labella/dist/labella.min.js"></script>
<script src="bower_components/d3kit-timeline/dist/d3kit-timeline.min.js"></script>

Choice 2: AMD

If you use requirejs, this library support AMD out of the box.

require.config({
  paths: {
    d3:    'path/to/d3',
    d3kit: 'path/to/d3Kit',
    labella: 'path/to/labella',
    'd3kit-timeline': 'path/to/d3kit-timeline'
  }
});
require(['d3kit-timeline'], function(d3KitTimeline) {
  // do something with d3KitTimeline
});

Choice 3: node.js / browserify

d3kit-timeline also supports usage in commonjs style.

var d3KitTimeline = require('d3kit-timeline');

Author

Krist Wongsuphasawat / @kristw

Copyright 2015-2017 Krist Wongsuphasawat. Licensed under the Apache License Version 2.0

d3kit-timeline's Issues

How to make interactive labels?

Hi to everyone.

How can the label be interactive. For example, execute a function when I click on a label

How to align a bunch of timelines on zero

Maybe I'm being dense, but I'm having a hard time figuring out how to have linear scale/axes on multiple timelines line up with zero in the middle. The reason is because each timeline has an index date and I want all events to display relative to this date.

My approach is: for each timeline I set the domain option to [ - max(abs(ext[0])), max(abs(ext[1])) ]. So each timeline from zero to the margin on either the left or right, but might not fill up the other side.

I'm getting two problems, probably resulting from my own bugs, but since I'm not sure how to do it right, it makes it harder to find my own bugs.

1. When I have multiple timelines they seem to all use the same domain even though I'm setting each timeline's domain, as far as I can tell, in its own scope. All the dots are getting squeezed very close to zero (which is in the right place in the middle of all the timelines.)

2. In a context with only one timeline, d3kit-timeline seems to ignore the domain I'm setting and place the zero where it needs to to fill out the whole timeline.

I can put together a simplified example if needed.

Not working in IE10 & IE11

The company I'm working with is interested in trying to incorporate this into the application, but I'm noticing some compatibility issues for IE10 & IE11. Are there any workarounds?

...besides the obvious of fixing IE!

resizeToFit() not working

Resize to fit doesn't appear to work for me. It is cropping the timeline at the initialHeight/Width boundaries.

Calling with:

chart.data(data).visualize().updateDimensionNow().resizeToFit();

and

chart.data(data).updateDimensionNow().resizeToFit().visualize();

Making it responsive in Bootstrap & label Auto layout option

Hi, this is very nice, can you please share some info.

• what option tells it to resize/be responsive if the browser size changes inside a bootstrap div.
• Also, what is the option to ensure it can auto/arrange/non-overlap labels.
• how to place font awesome icons in labels?
• What if the date is passed in the json? as a date and for e.g. not new date(3/2/2017), but 03/02/2017

thanks.

Multiline label

Hi,
I'm new in web development. This library is wonderful and I've a lot of questions. So, how can I do a multiline label text? Not a wrap text, I need to set line1=blabla, line two=bloblo.

Tanks a lot,

Overflow not handled well

When I change the demo code and clump a bunch of entry times together this pushes some of the labels off the bottom:

const data = [
    { time: new Date(1977, 4, 25), episode: 4, name: "A New Hope" },
    { time: new Date(2015, 11, 18), episode: 7, name: "The Force Awakens" },
    { time: new Date(2015, 11, 18), episode: 7, name: "The Force Awakens" },
    { time: new Date(2015, 11, 18), episode: 7, name: "The Force Awakens" },
    { time: new Date(2015, 11, 18), episode: 7, name: "The Force Awakens" },
    { time: new Date(2015, 11, 18), episode: 7, name: "The Force Awakens" },
    { time: new Date(2015, 11, 18), episode: 7, name: "The Force Awakens" }
];

Result:

Is there any way to avoid this happening?

Ideally I'd like it to look something like this (courtesy of my amazing paint skills):

Is this possible?

d3 not loaded when using require?

I'm trying to load d3kit-timeline through require (NPM), but get the following error:
"Cannot read property 'scale' of undefined"

Also https://tonicdev.com/npm/d3kit-timeline doesn't work, likely the same issue.

It seems that d3 is not loaded correctly, is there possibly something wrong in the dependency definition? I haven't had time yet to dig deeper, but could this be related to d3/d3#1693 or d3/d3#2615?

Is this project dead?

The dependencies are definitely out of date

how can I get the clicked position on the timeline corresponding time?

How to implement labels on both up and down sides?

Thanks for the great library.

Could someone please guide how to have labels on both up and down sides?

Basically, I have two categories of labels that one should show only up and the other one down.

Any help would be greatly appreciated.

Skeleton missing functionnality

I'm using your lib since few weeks it fits clearly with my exceptations, but i had to add an access to skeleton's nodes to update automatically height of chart like there http://twitter.github.io/labella.js/ when you add nodes. In horizontalTimeline.js, you can see the line that fits the height automatically:
skeleton.height(height + options.margin.top + options.margin.bottom);
and this thing is impossible to do with your lib at the moment.
I thought to add skeleton all free or juste add
var nodes = skeleton.nodes;
at the begining.

TypeError: d3KitTimeline is not a constructor

I followed the README, and got TypeError: d3KitTimeline is not a constructor.
And I have tried to import d3kit-timeline via <script> and node.js / browserify, the same result.

feature request: font weight and other styles

It would be great if we can make certain labels bold, underlined, etc.

labels are very small in in Bootstrap modals

The scripts are copied from your example. But when put in modals, the labels are corrupted. See http://plnkr.co/edit/lAjGHx9lk8DgTOALrVMs

allow non-time/Date based data

Fantastic work with this and labella! I know that the purpose of this is clearly to communicate date time, so please disregard if out of scope. Could the scale be exposed in options so we could use d3.scale.linear instead of d3.time.scale? Based on my cursory reading of the code, it seems this line could accept this option, and everything would work. As an example, consider the use case presented for the htmlwidget wrapper of communicating time of goal in a soccer game where the scale would be 0 to about 90.

How to wrap label text?

Rendering in hidden div

When rendering the timeline in a div that is hidden on creation the labels overlap, and are not formatted when unhidden. Any way to fix this?

Is there a way to control the color of the label?

Received this question from email.

Hope you are doing good !!

I came to know about your d3Kit-timeline library. This is wonderful.
I wanted to know is there a way to control the color of the label. I have to display several items on the time line, but the depending upon some condition the label color should be either green, red or black.
Following is my scenario:-

suppose I have few country name, depending upon the continent these countries labels color should appear on the time line.

Europe

UK - Red color
Ireland - Red color
Germany - Red color
France - Red color

America

Canada - Yellow color
USA - Yellow color
Brazil - Yellow color

Asia

Japan - Blue color
India - Blue color
China - Blue color

please help me to accomplish this.

Regards,
Shaheen Ahmad