Writing Custom React Hooks for D3 Visualizations

In late 2018, the React development team introduced hooks into version 16.8 of the React library. Shifting from class components to functional components, 

 provide a cleaner pattern for reusing stateful logic between components without relying on 

 (also known as "wrappers"), which add unnecessary levels to the component hierarchy, and 

, which are messy because of the amount of code they add to the JSX returned by the 

In class components, lifecycle methods and component state are rigidly bound to a particular component. Since class components define each lifecycle method only once, a lifecycle method often contains lots of unrelated logic, such as the 

 lifecycle method setting up different event listeners and fetching data from a remote API endpoint. Performing all of these tasks within a single lifecycle method increases the likelihood of introducing bugs and unintended behavior. However, in functional components, all of this logic can be distributed into separate hooks to share this logic with other functional components.

, handle component state and side-effects (

 consolidates multiple lifecycle methods into a single hook) respectively and make it easy to extract reusable snippets of code into smaller units of functionality. They serve as the building blocks for composing custom hooks. As a React application grows and becomes more complex to accommodate new features, writing components as functional components and delegating shareable logic to custom hooks allow components to not only be lighter, but also, flexible and maintainable.

Below, I'm going to show you how to write custom React hooks.

When writing custom hooks, there are some best practices that improve the clarity of these hooks for other developers. 

By convention, the name of a custom hook follows camel casing and starts with the 

 prefix. Additionally, the name of the hook should describe its purpose. For example, a hook named 

 implies a hook that fetches (and processes) CSV data and notifies the component when the data is available for the component's rendering.

The signature of a custom hook does not adhere to any strict rules. It can accept any number of arguments of any type and return any number of values of any type.

Custom hooks follow all of the same rules as built-in hooks:

Whenever a hook is called within a component, it has isolated local state that is independent of other hook calls. If you call the twice in a single component or call it in two different components, then each call yields state values unaffected by other calls.

In this tutorial, we will create multiple draggable, resizable widgets, which are common in analytics dashboard. Each widget displays a simple data visualization. To keep the example simple, there will only be two widgets: one displays a bar chart that shows the frequency of a categorical variable (flower species) and one displays a scatterplot that plots two quantitative variables (petal length against petal width). Both of these visualizations consume the 

Try it out in the CodeSandbox demo below:

Often, functional components in React applications contain similar pieces of functionality such as subscribing to a 

 event. In this example, both widgets possess the following characteristics, which all require stateful logic:

If we extract these pieces of functionality and refactor them into custom hooks, then we can keep our code DRY and leverage them in future visualization components. With custom hooks, we can cleanly express complex logic.

For the characteristics listed above, let's create five custom hooks to encapsulate them:

When the user resizes a widget by dragging its bottom-right corner, the dimensions of the widget's visualization scale proportionally based on the new widget's new dimensions. When the height of the widget exceeds its base height, then the visualization's height will increase proportionally while preserving its base aspect ratio. When the height of the widget shrinks below its base height, then the visualization will maintain its base height (and width), and the user would need to scroll within the widget to view the hidden portions of the visualization.

 contains the starting dimensions (height, width and margins) of the visualization and the height of the drag bar. By knowing the starting dimensions of the visualization, the hook can calculate its aspect ratio and preserve the visualization's aspect ratio anytime the widget is resized.

 to observe for changes on a target, which in this case is the widget. Inside of the 

When resizing the widget, the current width and height of the widget are referenced as 

 respectively. However, when determining the current dimensions of the visualization, the drag bar height must be subtracted from the widget height to obtain the new visualization height. This height is multiplied by the base aspect ratio to obtain the new visualization width.

This hook returns the new visualization dimensions and a 

 to set to the resizable element. This element happens to be a 

 component, which represents the widget itself.

import { useEffect, useRef, useState } from "react";
import ResizeObserver from "resize-observer-polyfill";

const useDimensions = (baseDimensions) => {
  const [dimensions, setDimensions] = useState(baseDimensions);
  const ref = useRef(null);

  const aspectRatio = dimensions.width / dimensions.height;
  const { margins, dragBarHeight, height, width } = baseDimensions;

  useEffect(() => {
    const element = ref.current;

    const resizeObserver = new ResizeObserver((entries) => {
      if (!Array.isArray(entries) || !entries.length) {
        return;
      }

      const entry = entries[0];
      const currentDimensions = {
        margins,
        width: entry.contentRect.width,
        height: entry.contentRect.height - dragBarHeight
      };

      if (currentDimensions.height > dimensions.height) {
        setDimensions({
          margins,
          width: aspectRatio * currentDimensions.height,
          height: currentDimensions.height
        });
      } else {
        setDimensions({
          margins,
          width,
          height
        });
      }
    });

    resizeObserver.observe(element);

    return () => resizeObserver.unobserve(element);
  }, []);

  return [dimensions, ref];
};

export default useDimensions;

When the user clicks on the dark-gray bar within a widget and drags on it, the widget drags with respect to the mouse cursor's position. When the user releases it, the widget remains in the spot it was released at. If multiple widgets happen to overlap one another, then the most recently dragged widget appears above the others.

 contains a reference to the widget. Having this reference allows the hook to update the widget's position by setting its 

 CSS properties. To calculate the widget's position (with respect to its top-left corner):

To listen for dragging events, register event listeners on the events 

 to capture the new position of the mouse cursor and change the position of the widget using the above mentioned calculation. When the widget component is unmounted, the hook will unregister these event listeners to avoid memory leaks. 

, which the component can set to a reference of the element dedicated to triggering the drag event, which is the dark-gray bar. 

import { useEffect, useRef } from "react";

let zIndex = 999;

const useDragDrop = (ref) => {
  const triggerRef = useRef(null);

  useEffect(() => {
    const element = triggerRef.current;
    const targetElement = ref.current;

    const onMouseDown = (event) => {
      const shiftX = event.clientX - targetElement.getBoundingClientRect().left;
      const shiftY = event.clientY - targetElement.getBoundingClientRect().top;

      const moveAt = (pageX, pageY) => {
        targetElement.style.left = `${pageX - shiftX}px`;
        targetElement.style.top = `${pageY - shiftY}px`;
      };

      const onMouseMove = (event) => {
        moveAt(event.pageX, event.pageY);
      };

      moveAt(event.pageX, event.pageY);

      document.addEventListener("mousemove", onMouseMove);

      element.addEventListener("mouseup", () => {
        document.removeEventListener("mousemove", onMouseMove);
        element.onmouseup = null;
      });
    };

    const onDragStart = (_evt) => {
      return false; // Prevents native drag'n'drop for images, etc.
    };

    function onMouseDownStyle() {
      targetElement.style.position = "absolute";
      targetElement.style.zIndex = ++zIndex;
    }

    targetElement.addEventListener("mousedown", onMouseDownStyle);
    element.addEventListener("mousedown", onMouseDown);
    element.addEventListener("dragstart", onDragStart);

    return () => {
      targetElement.removeEventListener("mousedown", onMouseDownStyle);
      element.removeEventListener("mousedown", onMouseDown);
      element.removeEventListener("dragstart", onDragStart);
    };
  }, []);

  return [triggerRef];
};

export default useDragDrop;

To create data visualizations, you must provide them with data. 

 submodule to fetch CSV data from a remote source and parse it into an array of objects, which each represent a row in the CSV data. While waiting for the data to be fetched, a flag should be set to tell the component that the data is being fetched. Once the data is fetched, the flag should be toggled to tell the component that the data is available and ready to be used for rendering the data visualization.

 is a function that performs a transformation on each row of the CSV data and returns the transformed row. 

 is an optional function that performs a transformation on the entirety of the CSV data. 

This hook initializes the values of the state variables 

 respectively. Both of these values are returned by the hook to be accessed by the component that calls it. When the hook is first called, the data has not yet been fetched, so to indicate that it is being fetched, 

 hook, the hook fetches the CSV data. The 

 method and waits for the data to be received. Once received, this data is processed and the 

 state variable is set to this data. After the 

 state variable is set or an error is encountered while fetching the CSV data, set the 

 to indicate that the CSV data has either been fetched or failed to be fetched. When the 

 remains set to an empty array, so the resulting visualization will be empty.

import { useCallback, useEffect, useState } from "react";
import { csv } from "d3";

const useCsv = (url, formatRows, transformResponse) => {
  const [data, setData] = useState([]);
  const [isLoading, setIsLoading] = useState(true);

  const fetchData = useCallback(async () => {
    try {
      const response = await csv(url, formatRows);

      setData(transformResponse ? transformResponse(response) : response);
    } catch (err) {
      console.error(err);
    }

    setIsLoading(false);
  }, [url, formatRows, transformResponse]);

  useEffect(() => {
    fetchData();
  }, []);

  return { isLoading, data };
};

export default useCsv;

When integrating D3 into React, it is recommended to use D3 to perform calculations and use React to render the visualizations. When creating an axis, plotting data points at specific coordinates within a scatterplot or determining the height of a bar within a bar chart, we need a scale function that maps values from the data ("domain") to pixel values within the SVG canvas ("range"). For the scale function to extrapolate an appropriate pixel value for a value that does not exist within the data, you must pick a D3 scale function that accurately depicts the relationship between both sets of values. For a scatterplot, continuous quantitative data should be based on a linear scale (

). For a bar chart, categorical data should be based on an ordinal scale (

 contains the values needed to create a scale. By default, by only specifying the 

 options, the hook constructs a linear continuous scale, which scatterplots commonly use for plotting data points and generating axes. The 

 determines which specific field's value should be extracted from each record of the data to serve as the scale's domain. The 

 specifies the  values the domain should be mapped to.

Alternatively, you can customize the scale by specifying a different scale function (

). To apply rounding and padding to the range of a band scale (used for charts with an ordinal/categorical dimension), specify the 

 flag to add spacing between bands (bars in a bar chart).

To avoid recreating the scale whenever an unrelated state/prop value changes in the component calling the 

, and only recreate the scale when the value of the 

import { useMemo } from "react";
import { extent, scaleLinear } from "d3";

const useScale = (params) => {
  return useMemo(() => {
    if (!params) {
      return null;
    }

    const {
      data,
      accessorKey,
      domain,
      range,
      scaleFn,
      isRangeRound,
      padding
    } = params;
    let scaleChain = scaleFn ? scaleFn : scaleLinear;

    // Domain
    scaleChain = scaleChain().domain(
      domain ? domain : extent(data, (d) => d[accessorKey])
    );

    // Range
    if (isRangeRound) {
      // Apply spacing between bars in bar chart.
      scaleChain = scaleChain.rangeRound(range).padding(padding ? padding : 0);
    } else {
      scaleChain = scaleChain.range(range);
    }

    return scaleChain;
  }, [params]);
};

export default useScale;

To distinguish different categories in a visualization, map each category to a unique color. For example, the Iris data contains observations for multiple flower species. If the observations are plotted onto a scatterplot, then coloring each point helps to differentiate the observations by flower species. Visually, colors make it easy to identify patterns and clusters.

To create a color scale that maps each category to a unique color, use an ordinal scale, which maps a set of discrete values to a set of visual attributes. This scale should accept the flower species as the domain and the colors as the range. 

Since we already have a custom hook for creating scales, we can call 

 custom hook to generate this color scale by passing it a unique set of options.

 hook requires only one argument, but its fields are unpacked within the hook's signature: 

 represents the field within a record that contains the categorical value. To obtain a list of categories, extract the categorical value from each record, pass this list of values to a 

 to remove duplicates and convert the set back to an array with the 

 method. These categories will be memoized to avoid recreating them whenever an unrelated state/prop value changes in the component calling the 

This hook not only returns a color scale, but also the list of categories in case you want to render a legend within the visualization.

import { useMemo } from "react";
import { scaleOrdinal } from "d3";
import useScale from "./useScale";

const useColorScale = ({ data, key, colors }) => {
  const categories = useMemo(
    () => (key && colors ? Array.from(new Set(data.map((d) => d[key]))) : []),
    [data, key, colors]
  );

  const colorScale = useScale(
    key && colors
      ? {
          data,
          domain: categories,
          range: colors,
          scaleFn: scaleOrdinal
        }
      : null
  );

  return { categories, colorScale };
};

export default useColorScale;

Explore the demo to see how these custom hooks are used in the 

 components. Try writing some custom hooks for your React applications!

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Writing Custom React Hooks for D3 Visualizations

Responses (0)

Masterclasses

Tutorials

Fullstack React with TypeScript