Skip to content


Subversion checkout URL

You can clone with
Download ZIP
CoffeeScript CSS Ruby JavaScript
Branch: gh-pages
Failed to load latest commit information.
coffee update comments
css data selector
data data selector
js update to latest d3
Gemfile working version
Gemfile.lock update to latest d3
README.textile h2 for title working version
index.html update to latest d3


Bubble Cloud Example Implementation

Demo of a word bubble cloud in D3.

For more info, check out the tutorial on


First Clone the Repository

git clone
cd vis

Remove Google Analytics Code

To make things easy on myself, This is the same code that is used to
power the live demo. As a consequence, my GA code is in there.

If you could be a nice person and remove or change that in your version,
I’d appreciate it.

Should be a script block around line 70.

View Demo

Because of how D3 handles importing data, this tutorial should be viewed using a local webserver to serve the pages.

Python webserver

You can start up a local webserver by using python’s built-in simple server:

For Python 2.xx

python -m SimpleHTTPServer -p 3000

For Python 3.xx

python -m http.server

This assumes you have Python availible from the command line.

On Windows, you will need to install Python. Here is one tutorial for that

Ruby webserver

The thin webserver, a ruby gem, can also be used:

thin start
# might have to run 'bundle install' first

Now go to

and you have a basic visualization

Start Coding

Open up coffee/ and start modifying the built in visualization to fit your needs.

Folder Organization

  • /
    • main vis area
  • /index.html
    • main page for your visualization. Loads coffeescript and javascript files.
  • /coffee/
    • coffeescript files.
  • /data/
    • data dump for .csv and .json files and other data files your vis uses.
  • /js/
    • javascript goes here. JS Libraries in libs directory
  • /css/
    • put your stylesheets in here

Add your own data

The format of the input data for each word set is a .csv file that looks something like:

# ...

If you have your own word list in a similar csv file, you can add it to the drop down list and view it in the demo by following these instructions:

Add your .csv file to the /data/ directory

Ensure your csv has a simple name, optimally [title].csv where [title] is a single word with no spaces or punctuation.

Then put your csv in the /data directory along side the other csv files.

Add your word list to index.html

First we will add an entry for your new word csv file to the index.html page. The drop-down box is created in index.html around line 28. It looks like this:

      <select id="text-select">
        <option value="sherlock">Sherlock Holmes</option>
        <option value="aesop">Aesop's Fables</option>
        <option value="alice">Alice in Wonderland</option>
        <option value="gulliver">Gulliver's Travels</option>

You will want to add your title and a key associated with that title to this list. Let’s say you have a csv file called gatsby.csv that has word counts for the book ‘The Great Gatsby’, then your select might look like this:

      <select id="text-select">
        <option value="gatsby">The Great Gatsby</option>
        <option value="sherlock">Sherlock Holmes</option>
        <option value="aesop">Aesop's Fables</option>
        <option value="alice">Alice in Wonderland</option>
        <option value="gulliver">Gulliver's Travels</option>

The value associated with the option is just a key that we will use in to load the right file.

Add entry in texts

Finally, we will add an entry to the texts Object in to associate our key with the file to load.

texts starts at line 407 in We need to add a new line that uses the key we put in our option value and the actual file name. In our example, we used the key gatsby and our file’s name is gatsby.csv, so the text object would look like:

texts = [
  {key:"gatsby",file:"gatsby.csv",name:"The Great Gatsby"}
  {key:"sherlock",file:"top_sherlock.csv",name:"The Adventures of Sherlock Holmes"}
  {key:"aesop",file:"top_aesop.csv",name:"Aesop's Fables"}
  {key:"alice",file:"alice.csv",name:"Alice's Adventures in Wonderland"}
  {key:"gulliver",file:"top_gulliver.csv",name:"Gulliver's Travels"}

To make things easier, ensure the order of the entries in texts matches the order of the option values in index.html.

Reloading the page, you should see your new bubble cloud appear!


To startup the server, you either need python, or a bunch of ruby gems (should be simplified in the future).

Run bundle install to get the gems needed. Gems listed in the Gemfile


Released under the MIT license:

Something went wrong with that request. Please try again.