d3-extended

d3.js Extended

This module is compatible with d3 v4. If you are looking for the v3 version you can find it on the v3 branch.

This module extends d3-selection with helpful functions which are similar to the jQuery API.

If you want to get to know more about this project, feel free to read the blog post: Replacing jQuery with d3.

Installation

npm

npm install --save d3-extended

git clone

git clone https://github.com/wbkd/d3-extended.git

Usage

ES6 modules

import * as d3Selection from 'd3-selection';
import 'd3-extended'; // d3Selection is now extended

CommonJS

const d3Selection = require('d3-selection');
require('d3-extended'); // d3Selection is now extended

Oldschool

You can use the compressed or uncompressed version. To use the plugin, include it after d3-selection in your HTML:

<script src="https://cdnjs.cloudflare.com/ajax/libs/d3-selection/1.1.0/d3-selection.min.js"></script>
<script src="path/to/d3-extended.js"></script>
<script>
  // d3 is now extended
</script>

Build

To build d3-extended run npm run build. This will create d3-extended.js and a minified version in the build folder.

Test

To run tests use npm test. Note: The tests require that you have phantomjs installed globally. If you see errors, try npm install -g phantomjs before running the tests.

API Documentation

DOM Manipulation

• prepend
• after
• before
• clear
• appendTo
• toggleClass
• addClass
• removeClass
• hasClass
• css
• show
• hide
• toggle

Traversing

• eq
• first
• last

Events

• on

Additional

• moveToBack
• moveToFront

DOM Manipulation

selection.prepend

jQuery equivalent: $.prepend

Inserts elements as first child of the current selection. Returns the new elements as a D3 selection.

selection.prepend(tagName);

Example:

d3.selectAll('li')
  .prepend('a')
  .text('Some Link')
  //do somethin else with the link

selection.after

jQuery equivalent: $.after

Inserts new elements after each element in the current selection. Returns the newly created elements as a d3 selection.

selection.after(tagName);

Example:

d3.selectAll('li')
  .after('li')
  .text('Item');
  //do something else with the inserted elements...

selection.before

jQuery equivalent: $.before

Inserts new elements before each element in the current selection. Returns the newly created elements as a d3 selection.

selection.before(tagName);

Example:

d3.selectAll('li')
  .before('li')
  .text('Item');
  //do something else with the inserted elements...

selection.clear

jQuery equivalent: $.empty

Removes all children of the current selection. Returns the current selection. We are using another name for this function as in jQuery, because d3 already has an empty function.

selection.clear();

Example:

d3.selectAll('ul')
  .clear();
  // ul element has no children anymore

selection.appendTo

jQuery equivalent: $.appendTo

Appends elements of the current selection to the target element. Returns the target selection.

selection.appendTo(tagName);

Example:

d3.selectAll('.foo').appendTo('.target');

selection.addClass

jQuery equivalent: $.addClass

Adds class to elements in the current selection. Returns current selection.

selection.addClass(className);

Example:

d3.selectAll('ul').addClass('active');
d3.selectAll('ul').addClass('class-a class-b'); //will add two classes

selection.removeClass

jQuery equivalent: $.removeClass

Removes class from elements in the current selection. Returns current selection.

selection.removeClass(className);

Example:

d3.selectAll('ul').removeClass('active');
d3.selectAll('ul').removeClass('class-a class-b'); //will remove two classes

selection.toggleClass

jQuery equivalent: $.toggleClass

Adds or removes class from elements in the current selection. Returns current selection.

selection.toggleClass(className);

Example:

d3.selectAll('ul').toggleClass('active');
d3.selectAll('ul').toggleClass('class-a class-b'); //toggle multiple classes

selection.hasClass

jQuery equivalent: $.hasClass

Checks if current selection has the passed class. Returns true or false.

selection.hasClass(className);

Example:

d3.selectAll('ul').hasClass('active');

selection.css

jQuery equivalent: $.css

Applies style to elements in the current selection. Returns the selection. Works in the same way like the D3 style function we only changed the name here.

selection.css(name, value);
selection.css(object);

Example:

d3.selectAll('.foo').css('display', 'block');

// or

d3.selectAll('.foo').css({
  display : 'none',
  background: 'red'
});

selection.show

jQuery equivalent: $.show

Diplays the current selection. Returns the selection.

selection.show();

Example:

d3.selectAll('.foo').show();

selection.hide

jQuery equivalent: $.hide

Hides the current selection. Returns the selection.

selection.hide();

Example:

d3.selectAll('.foo').hide();

selection.toggle

jQuery equivalent: $.toggle

Diplays or hides the current selection. Returns the selection.

selection.toggle();

Example:

d3.selectAll('.foo').toggle();

Traversing

selection.eq

jQuery equivalent: $.eq

Reduces current selection to the element with the passed index. Returns element. If you have a nested group, you can also specify the group index, to select a certain group.

selection.eq(index[, groupIndex]);

Example:

d3.selectAll('li').eq('0');
// returns first li element

selection.first

jQuery equivalent: $.first

Reduces the current selection to the first element. Then returns the reduced selection.

selection.first();

Example:

d3.selectAll('ul').first();

selection.last

jQuery equivalent: $.last

Reduces the current selection to the last element. Then returns the reduced selection.

selection.last();

Example:

d3.selectAll('ul').last();

Events

selection.on

jQuery equivalent: $.on

Works like the normal on function but now you can pass multiple event types like you know it from jquery. We took this function from the awesome d3-jetpack

selection.on(types [, listener[, capture]])

Example:

d3.select('li').on('click mouseenter mouseleave', function(d, i) {
  // do something
});

Additional Functions

These functions are not related to jQuery but they are little helper function we often use in our applications.

selection.moveToBack

Displays SVG element above the other ones.

selection.moveToBack();

Example:

d3.select('svg circle').moveToBack();

selection.moveToFront

Displays SVG element below the other ones.

selection.moveToFront();

Example:

d3.select('svg rect').moveToFront();

---

Contributors

• moklick
• chrtze
• tine
• mgold