Demo

https://benjamindickens.github.io/bubble-balls-demo/

Installation

npm install bubble-balls

Initialization

HTML

1. Add a container to your page with "balls" class.

<div class="balls"></div>

2. If you intend to use relative units you have to add another element inside with "balls-unit-example" class.

<div class="balls">
    <div class="balls-unit-example"></div> 
</div>

JS

3. Initialize the app in your js file and pass data with default set up or modify it manually with the option object.

import Balls from "bubble-balls";

new Balls(".balls", data, options)

Notes

Unfortunately right now you can't use absolutely the same data object for different instances on one page.

Options

data for balls

You can set styles right away for each ball like this

{
id: 1,
title: "Paris",
color: "royalblue",
background: "white",
borderColor: "royalblue",
}

or width image as a background

{
id: 4,
title: "Paris"
img: "/images/pages/home/values/common/bg-big.svg",
color: "yellow",
background: "gray",
borderColor: "yellow",
borderWidth: 5,
}

measurement units

1. Choose a measurement unit you are going to use in your app.

measurementUnit.name: "px" / "em" / "rem" || default: "px";

2. If the value you set is relative you also need to specify it in css for further calculation. It has to be equal to 10px.

Example with rem:

html {
  font-size: 0.69vw; //1440
}

.balls-unit-example {
  width: 1rem; //1rem ~ 10px at 1440 resolution of screen
}

on

Here you can add your custom functions.

on: {
      mouseover: () => { your code ...} || default: null,
      mouseout: func || default: null,
      afterInit: func || default: null,
    }

titlePropertyName

To specify what propery you are going to use for titles of balls.

titlePropertyName: "string" || default: "title"; 

imgPropertyName

To specify what propery you are going to use for titles of balls.

imgPropertyName = "string" || default: "img";

groupParam

Property name you use to divide babbles into groups for example by "country"

groupParam: {
    name: "string" || default: null,
};

radiusParam

Set property name to specify calculation radius of balls with dynamic scale by d3

radiusParam: {
    name: "string" || null,
    min: 'number' || this.measurementUnit.name === "px" ? 40 : 4,
};

draggable

To disable drag effect on balls set it to false.

draggable = "boolean" || default: true;

defaultStyles

You can modify default styles

defaultStyles: {
    color: "color" || default: "#000000",
    background: "color" || default: "#FFFFFF",
    borderColor: "color" || default: "#000000" ,
    borderWidth: "px" || default: 2,
}

groupsStyles

You can pass array width style objects. Those will apply to groups follow their indexe. ANother way is to specify styles for cirtain group by its group index or name if it sets.

groupsStyles: [
              {
               color: "royalblue",
               background: "white",
               borderColor: "royalblue",
               borderWidth: 0,
              },
               
               or with group name 
               
              {
               groupName: index of group or group name you specify 1,10, "General Motors"
               color: "yellow",
               background: "red",
               borderColor: "yellow",
               borderWidth: 5,
              },
              ] || default: null;

dynamicFontSize

Recalculate a font size of a title to fit a container and set min possible font.

dynamicFontSize: {
    init: options?.dynamicFontSize?.init || true,
    min: "number" || default: 10 or 1 if (measurementUnit.name !== "px" ),
};

forces

Specify forces applied to the balls

forces: {
    collisionMultiplier: "number" || default: 1.2, //create space between balls
};

dimensions

dimensions: {
    padding: "number" || default : this.measurementUnit.name === "px" ? 10 : 1, //padding on edges of the container to avoid overlaping.
    defaultRadius: "number" || default : this.measurementUnit.name === "px" ? 60 : 6, //default value if a radius property is not set and radiusParam not specify as well
    cols: numbers || default : 1, // specify how many columns for different group the container has it will add forces point
};

breakpoint

The value of @media (in pixels).

breakpoint: number || default: 667;