d3-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](http://phantomjs.org/) 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