@teociaps/bubble-chart

@teociaps/bubble-chart is a library for creating custom animated bubble charts using D3.js. This package provides a flexible and customizable way to visualize data in a bubble chart format, with support for animations and dynamic styling.

Installation

npm:

npm install @teociaps/bubble-chart

Yarn:

yarn add @teociaps/bubble-chart

Usage

Importing the Library

ES Modules (ESM)

If you're using ES Modules (e.g., in a modern JavaScript project or in a TypeScript environment), you can import the library like this:

import { createBubbleChart, BubbleData, BubbleChartOptions } from '@teociaps/bubble-chart';

CommonJS (CJS)

If you're working in a Node.js environment or any project using CommonJS modules, you can require the library like this:

const { createBubbleChart } = require('@teociaps/bubble-chart');

Creating a Bubble Chart

This library includes TypeScript definitions. Here's a basic example of how to create a bubble chart:

import { createBubbleChart, BubbleData, BubbleChartOptions } from '@teociaps/bubble-chart';

// Sample data
const data: BubbleData[] = [
  { name: 'Bubble 1', value: 10, color: 'red' },
  { name: 'Bubble 2', value: 20, color: 'blue' },
  { name: 'Bubble 3', value: 30, color: 'green' }
];

// Chart options
const options: BubbleChartOptions = {
  titleOptions: {
    text: 'My Bubble Chart',
    fontSize: '18px',
    fill: 'black'
  },
  showPercentages: true
};

// Create bubble chart
let generatedSvg = createBubbleChart(data, options, 800, 600, '#chart-container');

Parameters

• data (BubbleData[]): An array of objects representing each bubble. Each object should have the following properties:

  • name (string): The name or label of the bubble.
  • value (number): The value that determines the size of the bubble.
  • color (string): The color of the bubble.
  • icon (optional string): URL of an icon to be displayed inside the bubble.

• chartOptions (BubbleChartOptions): Options for customizing the chart. This includes:

  • titleOptions (TitleOptions): Options for the chart title.
    • text (optional string): Title text.
  • fontSize (optional string): Font size of the title.
  • fontWeight (optional string): Font weight of the title.
  • fill (optional string): Font color of the title.
  • padding (optional object): Padding around the title. Format { top?: number, right?: number, bottom?: number, left?: number }.
  • showPercentages (optional boolean): Whether to display percentages inside bubbles.

• width (number): Width of the SVG container. Defaults to 800.

• height (number): Height of the SVG container. Defaults to 600.

• selector (optional string): CSS selector for the element to which the SVG will be appended. Leave out to only generate and return the SVG without appending it to your document.

Customization

You can customize the chart appearance by adjusting the chartOptions and titleOptions. The library also includes a createSVGDefs function that you can use to define SVG gradients and masks. In addition, you can change the style of your bubble chart through the CSS, like in the demo, or manipulate the generated SVG string from the createBubbleChart function.

Development

Running Tests

To run tests, use:

npm test

Building the Project

To build the project for production, use:

npm run build

To build and watch for changes during development, use:

npm start

Running the Demo Locally

Start a local server to view the demo:

npm run start:demo

Contributing

If you'd like to contribute to the project, please submit a pull request or open an issue on the GitHub repository.

License

This project is licensed under the MIT License. See the License file for details.