Skip to content

lastboy/funnel-graph-js

 
 

Repository files navigation

D3 Funnel Graph

Latest LTS version npm GitHub file size in bytes GitHub GitHub last commit Changelog

Funnel Graph JS is a library for generating funnel charts using SVG, utilizing D3 JS
It supports horizontal and vertical funnel charts, offers options for solid colors and gradients, and can generate two-dimensional funnel charts.

This project is a fork of the funnel-graph-js project initiated by greghub. It has been entirely refactored using D3.js, although the core code that creates the paths remains unchanged.
The funnel graph is created as a single SVG unit, without combining any HTML elements except for the tooltip. This approach ensures a single responsive graph that can be dynamically updated and resized without needing to recreate the graph.

New Features

  • Graph Update without Recreation
    The graph can now be updated without needing to recreate it.

  • Fully Responsive Graph
    The graph, including text information and dividers, is now fully responsive.

  • Toggle Text Information
    Text information can be dynamically displayed or hidden.

  • Tooltip Support
    Tooltips are available over each area path for additional context.

  • Clickable Paths
    Paths within the graph are now clickable, with configurable callback functionality.

  • Clickable Labels
    Support has been introduced for adding click handlers to the label area.

  • Label and Tooltip Formatting
    Handlers have been added to customize the formatting of labels and tooltip displays.

Demo

Support for Vue, React, and Other Frameworks

Build

> yarn
> yarn build 

Installation

npm i d3-funnel-graph

JS:

import FunnelGraph from 'd3-funnel-graph';
// or import "d3-funnel-graph/dist/css/funnel-graph.min.css"

SCSS:

@import "http://github.com/d3-funnel-graph/dist/scss/variables.scss"
@import "http://github.com/d3-funnel-graph/dist/scss/mixin.scss"
@import "http://github.com/d3-funnel-graph/dist/scss/d3.scss"

Usage

var graph = new FunnelGraph({
    container: '.funnel',
    gradientDirection: 'horizontal',
    data: {...},
    displayPercent: true,
    direction: 'horizontal',
    width: 800,
    height: 300,
    margin: { 
      top: 120, 
      right: 60, 
      bottom: 60, 
      left: 60, 
      text: { left: 10, top: 0 } 
    },
    callbacks: {
        click: (event, opts) => {
            // path click by a section
        },
        label: (event, opts) => {
            // top label click
        }
    },
    format: {
        value: (opt) => { 
          // format the top label value
        },
        tooltip: (opt) => {
          // format the tooltip value
        }
    }
});

graph.draw();
// use graph.destroy() for cleanup

FunnelGraph Class Configuration

  • container
    Selector name (e.g., .selector).

  • width
    The width of the chart in pixels (e.g., 600).

  • height
    The height of the chart in pixels (e.g., 400).

  • labels
    Labels to be displayed on each section (e.g., ['Impressions', ...]).

  • subLabels
    Used in the tooltip for two-dimensional charts (e.g., ['Direct', ...]).

  • colors
    Overrides the default colors (e.g., [ ['#000', ... ], ]).

  • values
    The values of the graph (e.g., [ [3500, ...], ]).

  • margin
    Margins for the info text (e.g., { top?, right?, bottom?, left?, text: { left?, top? } }).

  • gradientDirection
    Direction of the gradient ('vertical' | 'horizontal').

  • callbacks
    Object for handling user actions (e.g., { 'click': () => {} }).

    • click
      Callback function for click events.

      • Signature:
        ({ index, value, label, subLabel, sectionIndex }) => {}

      • Parameters:

        • index: The index of the path item that was clicked.
        • sectionIndex: The index of the section containing the clicked path item.
        • value: The value associated with the clicked item.
        • label: The label of the clicked item.
        • subLabel: The sub-label of the clicked item (if applicable).
    • tooltip
      Callback function for tooltip events, overriding the default implementation.
      (event, { label, value, x, y }) => {}

    • tooltipLabel
      Callback function for tooltip events, overriding the default implementation.
      (event, { label, value, x, y, sectionDetails }) => {}

      • Signature:
        (event, { label, value }) => {}
    • label
      Callback function for label events.

      • Signature:
        (event, { index, value, label, subLabel, sectionIndex }) => {}
  • format
    Formatting options for text display.

    • value
      Callback function to format values.

      • Signature:
        ({ value }) => {}
    • tooltip
      Callback function to format tooltip content.

      • Signature:
        (opts) => {}
  • displayPercent
    Whether percentages should be displayed (true | false).

  • details
    Whether details should be displayed (true | false).

  • tooltip
    Whether the tooltip should be displayed ((default) true | false).

  • tooltipLabel
    Whether the tooltip label should be displayed (true | false (default)).

    Note: Tooltip display depends on the details display for range calculations according to the dividers.

  • resize
    Configuration for resizing the graph's paths based on container dimensions.

    • factor
      Adjustment factors for dimensions.

      • width: The width factor (default 0.4).
      • height: The height factor (default 0.4).
      • wait: The wait time (in milliseconds) before invoking the resize callback.
  • responsive
    When true, the SVG's width and height are set to 100%. The configured width and height are set in the viewBox.

    Note: Ensure the parent DIV elements are set to 100% for a properly resized graph.

  • responsiveWidth
    Enables exclusive responsive width.

  • responsiveHeight
    Enables exclusive responsive height.

Other Download and Import Options

Go to the code section of the repository and download the ZIP file.
Then, Use the provided resources according to your environment. You can use them directly in plain HTML or by importing (ES6+) them into your project.

CDN:

<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/lastboy/funnel-graph-js@master/dist/css/funnel-graph.min.css">

<script src="https://cdn.jsdelivr.net/gh/lastboy/funnel-graph-js@master/dist/js/funnel-graph.min.js"></script>

CSS:

<link rel="stylesheet" type="text/css" href="../dist/css/funnel-graph.min.css">

JS:

<script src="../dist/js/funnel-graph.min.js"></script>

Responsive Graph

Using the Responsive Flag

  • To create a responsive graph, the wrapper div elements must have a width and height set to 100%.
  • Set the responsive flag to true. This ensures the SVG's width and height are set to 100% of the wrapper dimensions.
  • Adjust the graph's width and height to maintain an appropriate aspect ratio that fits your page layout. This will define the viewBox dimensions (e.g., 800/200, 100/100, etc.).

Resize Configuration

This section can be used with the responsive flag or as a standalone solution. By setting the Resize configuration with the factor properties (width and height), you can make the graph responsive to window resizing and position it precisely as needed.

About

SVG Funnel Graph Javascript Library

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 91.7%
  • SCSS 8.3%