Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here


Placing labels on a timeline without overlap.

Subscribe to updates I use labella.js

Statistics on labella.js

Number of watchers on Github 3552
Number of open issues 5
Average time to close an issue 6 days
Main language JavaScript
Average time to merge a PR about 9 hours
Open pull requests 3+
Closed pull requests 2+
Last commit over 2 years ago
Repo Created over 4 years ago
Repo Last Updated over 1 year ago
Size 3.41 MB
Organization / Authortwitter
Page Updated
Do you use labella.js? Leave a review!
View open issues (5)
View labella.js activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating labella.js for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

Docs Introduction | Development | Demo   ////   API Reference Force | Node | Renderer

Labella.js NPM version Build Status

Labels should be beautiful.

If you try to place labels for points on a timeline (or any 1D space), one common problem is the labels often overlap. How about making the labels push each other and find where they can stay with overlapping?

Moreover, if you are looking for a ready-to-use timeline component with Labella's smart labeling instead of building your own timeline from scratch, check out d3Kit-timeline.

Note: For users who are upgrading from v0.x.x to v1.x.x. The API has changed. force.start() and force.on() are deprecated. Both are replaced by force.compute() which has to be called slightly differently. Please read the change logs.


npm install labella --save


bower install labella --save


// idealPos: The most preferred position for each label
// width:    The width of each label
var nodes = [
  new labella.Node(1, 50), // idealPos, width
  new labella.Node(2, 50),
  new labella.Node(3, 50),
  new labella.Node(3, 50),
  new labella.Node(3, 50),

var force = new labella.Force()

// The rendering is independent from this library.
// User can use canvas, svg or any library to draw the labels.
// There is also a built-in helper for this purpose. See labella.Renderer

Import into your project

Choice 1. Global

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

<script src="labella.min.js"></script>
Choice 2: AMD

If you use requirejs, Labella.js support AMD out of the box.

require(['path/to/labella'], function(labella) {
  // do something
Choice 3: node.js / browserify

Labella.js also supports usage in commonjs style.

var labella = require('path/to/labella');


The dist directory contains four variations of this library:

  • labella.js and labella.min.js : Core functionalities. This is what you will need for regular use.
  • labella-extra.js and labella-extra.min.js (since v1.1.0) : Same content with the above bundle plus labella.util and labella.metrics, which are special modules for demo/evaluation.


Krist Wongsuphasawat / @kristw

Copyright 2015 Twitter, Inc. Licensed under the Apache License Version 2.0

labella.js open issues Ask a question     (View All Issues)
  • about 3 years Upgrade to D3 v4
  • almost 4 years Idea: Position labels above&below resp left&right the timeline
labella.js open pull requests (View All Pulls)
  • nodeHeight as a function
  • Fix typo on the github page
  • Make sub-heading visible on the github page
labella.js questions on Stackoverflow (View All Questions)
  • Timeline with labella.js
labella.js list of languages used
Other projects in JavaScript