Introduction

ReGraph is a library of React components and analysis functions for client-side visualization of connected data.

You can try out ReGraph directly in your browser by opening a live code Playground and when you're ready, our tutorials can help you add ReGraph to your existing app or help you create a brand new ReGraph app.

ReGraph includes two visualization components - a chart to draw relationships between connected entities, and a time bar to represent events occurring over time:

import React from 'react';
import ReactDOM from 'react-dom';

import { Chart } from 'regraph';

export default function BasicChart() {
  const settings = {
    options: {
      navigation: false,
      overview: false,
      backgroundColor: 'rgb(61, 72, 82)',
    },
    onWheel: ({ preventDefault }) => {
      preventDefault();
    },
  };
  const items = {
    node1: {
      color: '#5fe3bf',
    },
    node2: {
      color: '#5fe3bf',
    },
    link1: {
      id1: 'node1',
      id2: 'node2',
      color: 'rgb(4, 129, 112)',
      width: 4,
    },
  };
  return <Chart items={items} {...settings} />;
}

ReactDOM.render(<BasicChart />, document.getElementById('app'));

Loading Chart

import React from 'react';
import ReactDOM from 'react-dom';

import { TimeBar } from 'regraph';

export default function BasicTimeBar() {
  const items = {
    event1: {
      times: [
        {
          time: {
            start: Date.now() - 15000000,
          },
        },
      ],
    },
    event2: {
      times: [
        {
          time: {
            start: Date.now() - 10000000,
            end: Date.now() + 10000000,
          },
        },
      ],
    },
  };
  const settings = {
    options: {
      backgroundColor: 'rgb(81, 95, 108)',
      style: {
        color: 'rgb(45, 205, 168)',
        hoverColor: 'rgb(7, 156, 131)',
      },
      sliders: {
        color: 'rgba(36, 44, 50, 0.5)',
        lineColor: 'rgb(81, 95, 108)',
      },
      labels: {
        fontColor: 'rgb(123, 135, 147)',
      },
      scale: {
        hoverColor: 'rgb(81, 95, 108)',
      },
    },
    onWheel: ({ preventDefault }) => {
      preventDefault();
    },
  };

  return (
    <TimeBar
      items={items}
      {...settings}
      selection={{ event2: true }}
      selectionColor="rgb(242, 119, 110)"
    />
  );
}

ReactDOM.render(<BasicTimeBar />, document.getElementById('app'));

Loading Chart

Add ReGraph to your App

Download the latest version of ReGraph:

For Safari browsers, hold the ⌥ Option key when pressing the Download button to download the correct .tgz format.

Copy the ReGraph bundle into your project directory. Do not change the file name.

cd ~/path/to/project
cp ~/Downloads/ .

Install the bundle as a local package from inside your project directory using a package manager:

npm install file:

yarn add ./

pnpm install file:

Now you can import ReGraph into your project:

import React from 'react';
import { createRoot } from 'react-dom/client'; // enables concurrent rendering
import { Chart } from 'regraph';

const items = { 
 node1: { label: { text: 'Hello World!' } }  // data in JSON where node1 is node id
};
const jsx = <Chart items={items}/>;
const container = document.getElementById('root');
const root = createRoot(container);
root.render(jsx);

Create New ReGraph App

If you don't have an existing project, you can create one with Vite using your preferred package manager. Follow the Vite Getting Started guide or run these commands to create a React Vite app:

npm create vite@latest my-regraph-app -- --template react

yarn create vite my-regraph-app --template react

pnpm create vite my-regraph-app --template react

Once this process has completed, start a development server:

cd my-regraph-app
npm install
npm run dev

cd my-regraph-app
yarn
yarn dev

cd my-regraph-app
pnpm install
pnpm run dev

By default, Vite runs a development server at http://localhost:5173.

Next, download the latest version of ReGraph:

For Safari browsers, hold the ⌥ Option key when pressing the Download button to download the correct .tgz format.

Move the download into your new project's root folder. If you are on a UNIX-like operating system, you can do this from the terminal:

cp ~/Downloads/ .

From your project's root folder, install the bundle as a local package:

npm install file:

yarn add ./

pnpm install file:

Next, open the App.jsx file in the src folder. This is where the component is declared. We will replace the boilerplate application with a ReGraph Chart component.

First, replace the import statements with an import statement for ReGraph:

import { Chart } from 'regraph';

And then replace the App() function with a new function:

function App() {
  return (
    // returns a div with a ReGraph Chart that fills the viewport
    <div style={{ height: '100vh', width: '100vw' }}>
      <Chart
        // a dictionary where each key is an item id
        // and each value is the item's definition
        items={{ node: { label: { text: 'Hello World!' } } }}/>
    </div>
  );
}

You should now see a ReGraph chart with a single node.

The chart sets its height and width to equal the size of its parent element, so any style should be set on the parent element.

Now that you have your first project, here's a few suggestions on where to go next if you're interested in...

• Adding font icons to items in your chart? Head to Fonts and Font Icons docs.
• Grouping the nodes or links in your chart? See Combining Nodes and Aggregating Links.
• Filtering chart by time or learning about changes over time? Read about the Time Bar.
• Running graph analysis or social network analysis? Take a look at Graph Analysis.

Updating

To update to the latest version of ReGraph, or to update your license, you need to replace your existing regraph.tgz bundle with the latest version and add it to your project.

First, download the latest version of ReGraph:

For Safari browsers, hold the ⌥ Option key when pressing the Download button to download the correct .tgz format.

Next, copy the bundle into your project. Do not change the file name.

cd ~/path/to/project
cp ~/Downloads/ .

If you already have a bundle in your project, you should delete it now.

Finally, remove the old version and install the bundle again from inside your project's root folder with your package manager:

npm uninstall regraph
npm install file:

yarn remove regraph
yarn add ./

pnpm remove regraph
pnpm install file:

To verify the update was successful, see the header comments of node_modules/regraph/index.js, or ask the package manager which version was installed:

npm list regraph

yarn list --pattern regraph

pnpm list regraph

If you are upgrading ReGraph after your license or your evaluation version had expired but your chart still isn't displaying correctly after the upgrade, try clearing the package manager's cache and installing the package again:

npm cache clean --force
npm install file:

yarn cache --clean
yarn add ./

# step not required for pnpm

If you need any help with updating please contact support.

Designing your Application

To help accelerate the design and build of branded graph visualizations that fit seamlessly into your application UI, download our free Figma Design Kit.

ReGraph forms part of the front end of your application and is entirely divorced from any backend architecture. It is up to you how to pull data into your page and format it into ReGraph's object format.

ReGraph is typically kept in a stateful container within your application. This container is responsible for updating ReGraph's state and integrating it with the other components.

State can exist simply in the state of a component, or a store provided by a React Hook, or in a Redux store. ReGraph is agnostic to this and behaves well in each environment, as long as its props are set correctly. See Re-rendering in ReGraph for more details.

Examples in this page typically assume that state is held in a component and passed to ReGraph by returning JSX from the component, as shown in the example below:

// Import various dependencies into the environment
import React from 'react';
import { Chart } from 'regraph';
import { fetchData, convertToReGraphFormat } from './myapp/helpers';

// Define the component
function App() {
  // Initialize app state
  const [state, setState] = React.useState({ items: {} });

  React.useEffect(() {
    // Load data from a data source
    fetchData().then((data) => {
      const items = convertToReGraphFormat(data); // your own custom formatter

      // When data is ready, set it on the component's state
      setState({ items });
    })
  }, []);

  // Create a ReGraph chart and push data into it from state
  return <Chart items={state.items} />
}

Note that the ReGraph source code needs to be sufficiently obfuscated before your application is distributed.

ReGraph Basics

The ReGraph chart is designed to visualize connected data sets. Although it can render a huge number of items, effective data visualization should aim to limit the amount of visible data. ReGraph comes loaded with features to filter and analyze your data. For examples, see our Graph Analysis stories.

The ReGraph time bar shows events over time. It can be used to filter items in a chart to events occurring within a specific time period, which provides an excellent way to reduce clutter in the chart. It can also highlight activity for a particular item.

ReGraph allows you to show a chart or time bar by describing its state with a series of objects. State can mean a number of things to ReGraph, including the data to render, the positions of nodes, layout and animation rules, viewport control and options. This state is passed to the component via props and will queue an animated redraw for the chart.

The full list of ReGraph props can be found in the API Reference.

Some state is controlled by ReGraph itself, for example when a layout is run and positions change, or when a user clicks on a node. In these cases, state changes are published to your application via an onChange event handler. You can hook to this to pass changes back to your application, for example to prevent the chart from moving during changes.

Data is loaded into ReGraph by passing a plain JavaScript object into the items prop. Each item can be one of the following types:

• Node: A single point or entity in the graph. Nodes typically render as circles, but can also be boxes.

• Link: A connection between nodes. Links must have an id1 and id2 property.

• Annotation: A note connected to item(s) in the chart. Annotations must have a subject property.

• Times: Items with a times property represent a point in, or period of, time. Times is only used by the time bar component. Times can be added to nodes or links.

Each key of the items object is the id of an item, and its value defines that item. To update an item, simply pass in a new object with updated values.

ReGraph relies on immutability to maintain state and understand when changes occur: see the Re-rendering in ReGraph section.

See the API Reference for a full guide to the available props and data formats.

Styling Items

Chart items such as nodes, links and annotations support a wide variety of customization options to make them suit your application. To do this, set properties on the item definitions in the items prop.

When you select a node or a link (default by clicking), it is styled with a selection style. This style is set using the selection property.

import React from 'react';
import ReactDOM from 'react-dom';

import { Chart } from 'regraph';

export default function ItemGallery() {
  const nodeColor = 'rgb(241, 93, 91)';

  const labelStyle = {
    backgroundColor: 'rgba(0,0,0,0)',
    color: 'rgb(202, 209, 216)',
    position: 's',
  };

  const linkStyle = {
    color: 'rgb(221, 60, 60)',
    width: 4,
  };

  const items = {
    bordered: {
      color: nodeColor,
      label: [
        {
          ...labelStyle,
          text: 'bordered',
        },
      ],
      border: { color: 'rgb(221, 60, 60)' },
    },
    enlarged: {
      color: nodeColor,
      label: [
        {
          ...labelStyle,
          text: 'enlarged',
        },
      ],
      size: 1.5,
    },
    image: {
      color: nodeColor,
      label: [
        {
          ...labelStyle,
          text: 'Image',
        },
      ],
      shape: 'box',
      image: '/img/rg-logo-square.png',
      border: { color: 'rgb(221, 60, 60)' },
    },
    link1: {
      ...linkStyle,
      id1: 'bordered',
      id2: 'enlarged',
    },
    link2: {
      ...linkStyle,
      id1: 'enlarged',
      id2: 'image',
      end1: {
        arrow: true,
      },
    },
    link3: {
      ...linkStyle,
      id1: 'enlarged',
      id2: 'image',
      end2: {
        arrow: true,
      },
      width: 1,
    },
  };

  const positions = {
    bordered: {
      x: -120,
      y: 0,
    },
    enlarged: {
      x: 0,
      y: 0,
    },
    image: {
      x: 120,
      y: 0,
    },
  };

  const settings = {
    options: {
      navigation: false,
      overview: false,
      backgroundColor: 'rgb(61, 72, 82)',
    },
    onWheel: ({ preventDefault }) => {
      preventDefault();
    },
  };

  return <Chart items={items} positions={positions} {...settings} />;
}

ReactDOM.render(<ItemGallery />, document.getElementById('app'));

Loading Chart

Sub-items

As well as customizing chart items, you can also specify various sub-items.

Sub-items are either decorations on chart items (such as labels or glyphs), or parts of chart items themselves (such as an annotation container). Sub-items can respond to events. The following sub-items can also have their own style rules:

• Halos - rings around nodes. The default node selection style uses halos. Each node support up to ten halos at any one time.
• Glyphs - decorations on nodes annotations, combos, or links. On nodes, annotations and combos, glyphs are placed around the border. On links, glyphs are placed next to the label at the link center or at link ends.
• Donuts - segmented borders around nodes which can indicate trends or relationships within that node, similar to a pie chart.
• Labels - additional information, such as text, font icons or images, to display with nodes, annotations or links.

The following example shows sub-items in action:

import React from 'react';
import ReactDOM from 'react-dom';

import { Chart } from 'regraph';

export default function SubItems() {
  const nodeColor = '#17BA99';

  const labelStyle = {
    backgroundColor: 'rgba(0, 0, 0, 0)',
    color: 'white',
  };

  const glyphStyle = {
    color: '#079C83',
    border: { color: '#8CEDD0', width: 2 },
  };

  const glyphLabelColor = 'white';

  const items = {
    node1: {
      color: nodeColor,
      label: {
        ...labelStyle,
        text: 'Halos',
      },
      halos: [
        {
          radius: 35,
          color: '#5FE3BF',
          width: 8,
        },
        {
          radius: 47,
          color: '#8CEDD0',
          width: 8,
        },
      ],
    },
    node2: {
      color: nodeColor,
      label: {
        ...labelStyle,
        text: 'Glyphs',
      },
      glyphs: [
        {
          ...glyphStyle,
          position: 'n',
          label: {
            color: glyphLabelColor,
            text: 'N',
          },
        },
        {
          ...glyphStyle,
          position: 's',
          label: {
            color: glyphLabelColor,
            text: 'S',
          },
        },
        {
          ...glyphStyle,
          position: 'e',
          label: {
            color: glyphLabelColor,
            text: 'E',
          },
        },
        {
          ...glyphStyle,
          position: 'w',
          label: {
            color: glyphLabelColor,
            text: 'W',
          },
        },
      ],
    },
    node3: {
      color: nodeColor,
      label: {
        ...labelStyle,
        text: 'Donuts',
      },
      donut: {
        border: {
          width: 2,
          color: '#3D4852',
        },
        segments: [
          {
            color: '#8BEED2',
            size: 1,
          },
          {
            color: '#8CEDD0',
            size: 1,
          },
          {
            color: '#5FE3BF',
            size: 1,
          },
        ],
      },
    },
  };

  const positions = {
    node1: { x: 0, y: -50 },
    node2: { x: -90, y: 50 },
    node3: { x: 90, y: 50 },
  };

  const settings = {
    options: {
      backgroundColor: 'rgb(61, 72, 82)',
      navigation: false,
      overview: false,
    },
    onWheel: ({ preventDefault }) => {
      preventDefault();
    },
  };

  return <Chart items={items} positions={positions} {...settings} />;
}

ReactDOM.render(<SubItems />, document.getElementById('app'));

Loading Chart

For more details and a full list of sub-item types, see the Sub-item section in the API Reference.

Interaction styling

Interaction styling is applied when an item or sub-item is interacted with, i.e. hovered or selected. The styling changes back to the values defined in the items prop automatically once the interaction is finished. This means that you don't need to manage item state when applying different styles for hovered or selected items. To apply interaction styling, use the onItemInteraction event and pass the new styling to the event's setStyle function.

If you're using both onItemInteraction and the selection Chart option to style an item, only the styling specified for selection will be applied.

import React from 'react';
import ReactDOM from 'react-dom';

import { Chart } from 'regraph';

const GlyphHoverStyle = {
  color: '#f15d5b',
  border: { color: '#fff', width: 2 },
};

const ItemHoverStyle = {
  color: '#f15d5b',
  border: { color: '#fff', width: 3 },
};

export default function InteractionStyling() {
  const onItemInteractionHandler = ({ hovered, id, setStyle, subItem }) => {
    let newStyle = { glyphs: [] };
    if (hovered && subItem && subItem.type === 'glyph') {
      newStyle.glyphs[0] = GlyphHoverStyle;
    } else {
      newStyle = ItemHoverStyle;
    }

    setStyle({ [id]: newStyle });
  };

  const items = {
    node: {
      color: '#17BA99',
      border: { color: 'rgb(7, 156, 131)', width: 1 },
      size: 1.2,
      data: { type: 'node' },
      label: {},
      glyphs: [
        {
          color: '#079C83',
          border: { color: 'rgb(241, 93, 91)', width: 1 },
          size: 1.2,
          position: 'ne',
          label: {
            text: 'Glyph',
          },
        },
      ],
    },
  };

  const settings = {
    options: {
      backgroundColor: 'rgb(61, 72, 82)',
      hoverDelay: 0,
      navigation: false,
      overview: false,
      selection: false,
    },
    onWheel: ({ preventDefault }) => {
      preventDefault();
    },
  };

  return <Chart items={items} onItemInteraction={onItemInteractionHandler} {...settings} />;
}

ReactDOM.render(<InteractionStyling />, document.getElementById('app'));

Loading Chart

Link Shapes

Link shape refers to the shape of a link path, and helps highlight particular aspects of your data structure for different chart layouts and combo arrangements. Direct links are used by default, but you can change that at chart level using the layout linkShape option. You can then fine-tune the appearance of your chart by specifying a different link shape at combo level using the arrangement linkShape option. See Using a mixture of link shapes for information about how to use multiple link shapes.

Link shape summary:

direct	The default. Direct links are straight lines that run directly between nodes. Well-suited to charts that concentrate on overall connectivity using organic, lens or radial layouts.
angled	Angled links provide an orthogonally branching shape between nodes in a hierarchical structure, aligned with layout orientation. Especially suited to sequential layouts. In beta from v5.1. Use priority links to highlight different paths, as shown in the Angled Links story.	Beta
curved	Curved links follow a smooth path between nodes in different levels of a hierarchical structure, aligned with layout orientation. Useful for hierarchical data, especially sequential layouts.

Leaflet Integration always uses direct links.

Using a mixture of link shapes Beta

In addition to using an overall link shape for your chart layout, with perhaps another for combo arrangements, you can also specify the link shape for an individual link, which takes precedence.

Setting an individual link's linkShape property, specifies its shape, and the direction in which it connects to its end nodes. This can be useful to represent different types of relationship in your chart.

For example, you might have a chart with a sequential component using angled links, and want to show the relationship between that, and another set of nodes, using curved links, as shown.

Explore this further in the Mixed Link Shapes story.

Multiple links between two nodes

By default ReGraph automatically spaces out multiple direct or curved links (as described in Link Shapes) running between two nodes by separating their midpoints. Direct links are separated to follow arcs, as shown, while curved links follow double curves.

Angled links can't helpfully be separated this way, so to focus on a critical path through a chart using angled links, use priority links.

Priority Links Beta

To help focus on a particular path through a dense and overlapping network of nodes and links, you can assign priority to particular links to show them clearly, and in front of other links. This can be useful when using angled links, as illustrated, which can overlap each other.

Explore the use of link priority, used to highlight the attack path in the Cloud Security showcase.

Advanced Node Styling

There are various reasons why your charts may need a custom node design:

• A high level of information (e.g. several pieces of information shown by single node)
• Dynamically changing data (e.g. strings or numbers in varying length)
• Different types of data (e.g. visual or numeric information, relative amounts)
• The specific design language of your application

Below are some examples of the ReGraph API for advanced node styling:

• shape: Sets width and height to get rectangular nodes.
• radius: Sets corner radius to node border.
• label: Accepts an array of one or more objects to create multiple labels with a large number of customizable properties such as image, position, border, margin, padding or textAlignment. This feature is currently in beta. See the Node Label API for details.

If your nodes contain images or font icons, you can control their scale and position using imageAlignment.

For more examples, see also the Node Gallery and Advanced Node Gallery stories.

import React from 'react';
import ReactDOM from 'react-dom';

import { Chart } from 'regraph';

export default function AdvancedStyling() {
  const shape = {
    height: 80,
    width: 'auto',
    minWidth: 250,
  };

  const nodeColor = '#17BA99';
  const textColor = '#fff';
  const alertColor = '#fedd03';
  const clearBackground = 'rgba(0, 0, 0, 0)';

  const border = {
    color: alertColor,
    radius: 15,
  };

  const items = {
    node1: {
      shape,
      color: nodeColor,
      border,
      label: [
        {
          fontIcon: {
            fontFamily: 'Font Awesome 5 Free',
            text: 'fas fa-exclamation-triangle',
          },
          position: {
            vertical: 'top',
            horizontal: 'right',
          },
          fontSize: 30,
          color: alertColor,
          backgroundColor: clearBackground,
          margin: '3 3 0 0',
        },
        {
          fontIcon: {
            fontFamily: 'Font Awesome 5 Free',
            text: 'fas fa-desktop',
          },
          position: {
            vertical: 'middle',
            horizontal: 'left',
          },
          fontSize: 70,
          color: textColor,
          backgroundColor: clearBackground,
          margin: '0 0 0 6',
        },
        {
          text: 'Service AB',
          position: {
            vertical: 20,
            horizontal: 60,
          },
          fontSize: 25,
          color: textColor,
          bold: true,
          backgroundColor: clearBackground,
          margin: '0 0 0 10',
        },
        {
          text: 'Status: ',
          position: {
            vertical: 45,
            horizontal: 60,
          },
          color: textColor,
          bold: true,
          backgroundColor: clearBackground,
          margin: '0 0 0 10',
        },
        {
          text: 'Storage at 90%',
          position: {
            vertical: 'inherit',
          },
          color: textColor,
          backgroundColor: clearBackground,
        },
      ],
    },
  };

  const settings = {
    options: {
      iconFontFamily: 'Font Awesome 5 Free',
      backgroundColor: 'rgb(61, 72, 82)',
      navigation: false,
      overview: false,
    },
    onWheel: ({ preventDefault }) => {
      preventDefault();
    },
  };

  return <Chart items={items} {...settings} />;
}

const FontReadyChart = React.lazy(() =>
  document.fonts.load("24px 'Font Awesome 5 Free'").then(() => ({
    default: AdvancedStyling,
  })),
);

export function AdvancedStylingDemo() {
  return (
    <React.Suspense fallback="">
      <FontReadyChart />
    </React.Suspense>
  );
}

ReactDOM.render(<AdvancedStylingDemo />, document.getElementById('app'));

Loading Chart

Label positioning

Labels are anchored to nodes from the outside or from the inside.

The position property accepts a string compass value to set the label outside the node, or an object with vertical and/or horizontal properties to set the label inside the node.

Set the position of images and font icons within node labels using position and margin. You can also control the scale of font icons using fontSize.

import React from 'react';
import ReactDOM from 'react-dom';

import { Chart } from 'regraph';

export default function NodeStyling() {
  const nodeColor = '#17BA99';
  const shape = { height: 250, width: 550 };
  const textColor = '#fff';
  const border = { radius: 5 };

  const insideLabelStyle = {
    backgroundColor: 'rgb(7, 156, 131)',
    color: textColor,
    fontSize: 25,
    border: {
      color: 'rgb(4, 129, 112)',
      radius: 5,
    },
  };
  const outsideLabelStyle = {
    backgroundColor: 'rgb(241, 93, 91)',
    color: textColor,
    fontSize: 25,
    border: {
      color: 'rgb(221, 60, 60)',
      radius: 5,
    },
  };

  const items = {
    node1: {
      shape: shape,
      color: nodeColor,
      border: border,
      label: [
        {
          text: 'n',
          position: 'n',
          ...outsideLabelStyle,
        },
        {
          text: 's',
          position: 's',
          ...outsideLabelStyle,
        },
        {
          text: 'e',
          position: 'e',
          ...outsideLabelStyle,
        },
        {
          text: 'w',
          position: 'w',
          ...outsideLabelStyle,
        },
        {
          text: 'ne',
          position: 'ne',
          ...outsideLabelStyle,
        },
        {
          text: 'nw',
          position: 'nw',
          ...outsideLabelStyle,
        },
        {
          text: 'se',
          position: 'se',
          ...outsideLabelStyle,
        },
        {
          text: 'sw',
          position: 'sw',
          ...outsideLabelStyle,
        },
        {
          text: '50, 50 world units',
          position: { vertical: 50, horizontal: 50 }, // world units
          ...insideLabelStyle,
        },
        {
          text: '(top, left)',
          position: { vertical: 'top', horizontal: 'left' },
          ...insideLabelStyle,
        },
        {
          text: '(top, right)',
          position: { vertical: 'top', horizontal: 'right' },
          ...insideLabelStyle,
        },
        {
          text: '(top, center)',
          position: { vertical: 'top', horizontal: 'center' },
          ...insideLabelStyle,
        },
        {
          text: '(middle, left)',
          position: { vertical: 'middle', horizontal: 'left' },
          ...insideLabelStyle,
        },
        {
          text: '(middle, center)',
          position: { vertical: 'middle', horizontal: 'center' },
          ...insideLabelStyle,
        },
        {
          text: '(middle, right)',
          position: { vertical: 'middle', horizontal: 'right' },
          ...insideLabelStyle,
        },
        {
          text: '(bottom, left)',
          position: { vertical: 'bottom', horizontal: 'left' },
          ...insideLabelStyle,
        },
        {
          text: '(bottom, center)',
          position: { vertical: 'bottom', horizontal: 'center' },
          ...insideLabelStyle,
        },
        {
          text: '(bottom, right)',
          position: { vertical: 'bottom', horizontal: 'right' },
          ...insideLabelStyle,
        },
      ],
    },
  };

  const settings = {
    options: {
      backgroundColor: 'rgb(61, 72, 82)',
      navigation: false,
      overview: false,
    },
    onWheel: ({ preventDefault }) => {
      preventDefault();
    },
  };

  return <Chart items={items} {...settings} />;
}

ReactDOM.render(<NodeStyling />, document.getElementById('app'));

Loading Chart

Multiple inline labels

By default, multiple labels on a node are stacked vertically from the top. There are two ways how to position multiple labels on the same line using the vertical option of position:

• set it to 'inherit' if the preceding label label has no vertical position set
• set it to the same value if the preceding label has a vertical position set

import React from 'react';
import ReactDOM from 'react-dom';

import { Chart } from 'regraph';

export default function InlineLabels() {
  const nodeColor = '#17BA99';
  const shape = { height: 180, width: 350 };
  const textColor = '#fff';
  const border = { radius: 5 };

  const precedingLabelStyle = {
    backgroundColor: 'rgb(7, 156, 131)',
    color: textColor,
    fontSize: 25,
    border: {
      color: 'rgb(4, 129, 112)',
      radius: 5,
    },
  };
  const followingLabelStyle = {
    backgroundColor: 'rgb(241, 93, 91)',
    color: textColor,
    fontSize: 25,
    border: {
      color: 'rgb(221, 60, 60)',
      radius: 5,
    },
  };

  const items = {
    node1: {
      shape: shape,
      color: nodeColor,
      border: border,
      label: [
        {
          text: 'no position',
          ...precedingLabelStyle,
        },
        {
          position: { vertical: 'inherit' },
          text: 'inline by inherit',
          ...followingLabelStyle,
        },
        {
          position: { vertical: 'bottom' },
          text: 'vertical position',
          ...precedingLabelStyle,
        },
        {
          position: { vertical: 'bottom' },
          text: 'inline by vertical position',
          ...followingLabelStyle,
        },
      ],
    },
  };

  const settings = {
    options: {
      backgroundColor: 'rgb(61, 72, 82)',
      navigation: false,
      overview: false,
    },
    onWheel: ({ preventDefault }) => {
      preventDefault();
    },
  };

  return <Chart items={items} {...settings} />;
}

ReactDOM.render(<InlineLabels />, document.getElementById('app'));

Loading Chart

Label sizing and label content

A label can either contain an image or text-based information such as text or a font icon.

Image labels have image set, and can be sized by specifying both maxWidth and maxHeight. You can also specify border and position them using margin and position, but other label settings are ignored.

Labels containing text or a font icon are sized, by default, to fit the content that's inside. In this case the ReGraph API lets you modify the label size and also customize the content inside:

• minWidth, minHeight: Set custom label size.
• textAlignment: Sets the alignment of content inside a label
• fontSize:'auto': Scales the font to any label size and zoom level.
• textWrap:'normal': Wraps the content on whitespace.
• maxWidth, maxHeight: Controls maximum size when text wrapping or automatic font sizing are used.

import React from 'react';
import ReactDOM from 'react-dom';

import { Chart } from 'regraph';

export default function LabelSizing() {
  const nodeColor = '#17BA99';
  const shape = { height: 180, width: 350 };
  const textColor = '#fff';
  const border = { radius: 5 };

  const labelStyle1 = {
    backgroundColor: 'rgb(7, 156, 131)',
    color: textColor,
    border: {
      color: 'rgb(4, 129, 112)',
      radius: 5,
    },
  };
  const labelStyle2 = {
    backgroundColor: 'rgb(241, 93, 91)',
    color: textColor,
    border: {
      color: 'rgb(221, 60, 60)',
      radius: 5,
    },
  };

  const items = {
    node1: {
      shape: shape,
      color: nodeColor,
      border: border,
      label: [
        {
          text: 'Default size label',
          position: { vertical: 'top' },
          margin: { bottom: 5 },
          ...labelStyle1,
        },
        {
          text: 'Custom size and text alignment',
          minWidth: 300,
          minHeight: 40,
          textAlignment: {
            horizontal: 'right',
            vertical: 'bottom',
          },
          margin: { bottom: 5 },
          ...labelStyle2,
        },
        {
          text: 'Automatic font sizing',
          fontSize: 'auto',
          margin: { bottom: 5 },
          ...labelStyle1,
        },
        {
          text: 'Max width, wrapped text, auto font size',
          textWrap: 'normal',
          fontSize: 'auto',
          maxWidth: 100,
          ...labelStyle2,
        },
      ],
    },
  };

  const settings = {
    options: {
      backgroundColor: 'rgb(61, 72, 82)',
      navigation: false,
      overview: false,
    },
    onWheel: ({ preventDefault }) => {
      preventDefault();
    },
  };

  return <Chart items={items} {...settings} />;
}

ReactDOM.render(<LabelSizing />, document.getElementById('app'));

Loading Chart

Layouts

ReGraph uses a layout algorithm to determine where to position nodes on the Chart.

Layouts in ReGraph are designed to help you understand the relationships between nodes. Generally, connected items will be positioned close to each other, with more highly connected items nearer the center of the chart.

Each of ReGraph's layouts use different rules to position nodes, offering a range of options suited to different data sets.

See the Layouts story to compare the different layouts available.

import React from 'react';
import ReactDOM from 'react-dom';
import _ from 'lodash';
import { Chart } from 'regraph';

function generateData(count = 20) {
  const items = {};
  for (let i = 0; i < count; i += 1) {
    items[i] = {
      color: '#5fe3bf',
    };
  }
  for (let i = 0; i < 30; i += 1) {
    const a = i < count ? i : _.random(0, count - 1);
    let b;
    do {
      b = _.random(0, count - 1);
    } while (a === b);
    const id = [a, b].sort().join('-');
    items[id] = {
      id1: a,
      id2: b,
      color: 'rgb(4, 129, 112)',
      width: 4,
    };
  }
  return items;
}

export default function SimpleLayout() {
  const data = generateData();

  const settings = {
    options: {
      navigation: false,
      overview: false,
      backgroundColor: 'rgb(61, 72, 82)',
    },
    onWheel: ({ preventDefault }) => {
      preventDefault();
    },
  };

  return (
    <Chart
      items={data}
      layout={{
        name: 'organic',
      }}
      {...settings}
    />
  );
}

ReactDOM.render(<SimpleLayout />, document.getElementById('app'));

Loading Chart

Running layouts

To set a layout, or to re-run a layout on existing data, pass an object to the layout prop on the Chart with the name of the layout, along with any required options. For more information, see the API Reference.

There are a variety of layout options available to customize your layouts.

After a layout has run and positions have been calculated, ReGraph will publish the new positions to the onChange handler. Note that the onChange handler is also invoked when the user drags an item.

import React from 'react';
import ReactDOM from 'react-dom';

import { Chart } from 'regraph';

const data = {
  node1: {
    color: '#5fe3bf',
    label: {
      color: 'rgb(61, 72, 82)',
      backgroundColor: 'rgba(0,0,0,0)',
    },
  },
  node2: {
    color: '#5fe3bf',
    label: {
      color: 'rgb(61, 72, 82)',
      backgroundColor: 'rgba(0,0,0,0)',
    },
  },
  node3: {
    color: '#5fe3bf',
    label: {
      color: 'rgb(61, 72, 82)',
      backgroundColor: 'rgba(0,0,0,0)',
    },
  },
  node4: {
    color: '#5fe3bf',
    label: {
      color: 'rgb(61, 72, 82)',
      backgroundColor: 'rgba(0,0,0,0)',
    },
  },
  link1: {
    id1: 'node1',
    id2: 'node2',
    width: 4,
    color: 'rgb(4, 129, 112)',
  },
  link2: {
    id1: 'node2',
    id2: 'node3',
    width: 4,
    color: 'rgb(4, 129, 112)',
  },
  link3: {
    id1: 'node3',
    id2: 'node4',
    width: 4,
    color: 'rgb(4, 129, 112)',
  },
  link4: {
    id1: 'node2',
    id2: 'node4',
    width: 4,
    color: 'rgb(4, 129, 112)',
  },
};

const buttonStyle = {
  backgroundColor: 'hsl(0, 70%, 55%)',
  border: 'none',
  borderRadius: '0.1rem',
  bottom: '1rem',
  boxShadow: '0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06)',
  color: 'hsl(14, 90%, 96%)',
  cursor: 'pointer',
  fontWeight: '700',
  letterSpacing: '0.02rem',
  opacity: 0.85,
  padding: '0.25rem 1rem',
  position: 'absolute',
  right: '1rem',
  textTransform: 'uppercase',
};

export default function PositionTracker() {
  const [state, setState] = React.useState({
    items: data,
    layout: {
      name: 'organic',
    },
  });

  const onChangeHandler = (change) => {
    if (change.positions) {
      setState((current) => {
        const { items: currentItems } = current;
        const items = { ...currentItems };
        Object.keys(change.positions).forEach((id) => {
          const pos = change.positions[id];
          items[id] = {
            ...items[id],
            label: {
              ...items[id].label,
              text: `x: ${Math.round(pos.x)}\n y: ${Math.round(pos.y)}`,
            },
          };
        });
        return {
          ...current,
          items,
        };
      });
    }
  };

  const runLayout = () => {
    setState((current) => {
      return {
        ...current,
        layout: { ...current.layout },
      };
    });
  };

  const onWheelHandler = ({ preventDefault }) => {
    preventDefault();
  };

  const { items, layout } = state;
  return (
    <div style={{ height: '100%', position: 'relative' }}>
      <Chart
        items={items}
        layout={layout}
        onChange={onChangeHandler}
        onWheel={onWheelHandler}
        options={{
          navigation: false,
          overview: false,
          backgroundColor: 'rgb(61, 72, 82)',
        }}
      />
      <button type="button" className="rg-button" onClick={runLayout} style={buttonStyle}>
        Layout
      </button>
    </div>
  );
}

ReactDOM.render(<PositionTracker />, document.getElementById('app'));

Loading Chart

Custom layouts

You can manually control the chart by setting the positions prop. This will prevent ReGraph's built-in layouts from running. Instead, ReGraph will animate items into position for you. You can use this to:

• Pass positions from an onChange event into the positions prop to prevent movement during changes as seen in the Filtering Data story.
• Define your own layouts:

import React from 'react';
import ReactDOM from 'react-dom';
import _ from 'lodash';

import { Chart } from 'regraph';

function generateData(count = 20) {
  const items = {};
  for (let i = 0; i < count; i += 1) {
    items[i] = {
      color: '#5fe3bf',
    };
  }
  for (let i = 0; i < 30; i += 1) {
    const a = i < count ? i : _.random(0, count - 1);
    let b;
    do {
      b = _.random(0, count - 1);
    } while (a === b);
    const id = [a, b].sort().join('-');
    items[id] = {
      id1: a,
      id2: b,
      width: 4,
      color: 'rgb(4, 129, 112)',
    };
  }
  return items;
}

function isNode(item) {
  return !item.id1 && !item.id2;
}

export default function CustomLayout() {
  const data = generateData();

  // Calculate a simple grid layout by setting
  // the x/y position of each node
  const positions = {};
  let x = 0;
  let y = 0;
  let cols = 0;
  _.each(data, (item, id) => {
    if (isNode(item)) {
      cols += 1;
      positions[id] = {
        x,
        y,
      };
      if (cols % 5 === 0) {
        y += 90;
        x = 0;
      } else {
        x += 90;
      }
    }
  });

  const settings = {
    options: {
      navigation: false,
      overview: false,
      backgroundColor: 'rgb(61, 72, 82)',
    },
    onWheel: ({ preventDefault }) => {
      preventDefault();
    },
  };

  // Passing a new view object will tell ReGraph to zoom
  // to fit all items after the layout has run
  const view = {};

  return <Chart items={data} positions={positions} view={view} {...settings} />;
}

ReactDOM.render(<CustomLayout />, document.getElementById('app'));

Loading Chart

Layout Types

You can see examples of all our layouts in our Layouts story.

Organic

Organic is a force-directed layout, making links similar lengths and reducing node and edge overlaps as they distribute items evenly across the chart.

Organic is the default layout in ReGraph. It is suitable for any type or size of data and it's particularly useful for finding patterns and symmetries.

Structural

The structural layout functions in a similar manner to a force-directed layout, but it groups together nodes with the same neighboring nodes. This makes it easier to see the general organization of a network.

By giving you an overview of the clusters within a network, the structural layout allows you to see groupings and patterns without the need to focus on any one element.

Sequential

The sequential layout is useful for displaying data with a clear sequence of links between distinct levels of nodes. It minimizes link crossings and makes efficient use of space, and is particularly well-suited to using an angled link shape, as shown.

Sequential automatically places nodes according to the specified orientation, and the direction of arrows on links. You can also customize the position of nodes using the level or top options, and refine the ordering in each level using orderBy.

When space is at a premium, you can use packing, stretch and stretchtype. You can also stack nodes with identical connections into grids using stacking, as shown in our Navigating Large Hierarchies story.

Radial

The radial layout arranges nodes in concentric circles around a selected subject in a radial tree. Each ‘generation’ of nodes becomes a new ring surrounding the previous generations.

This layout is a great option when dealing with networks with a large number of child nodes compared to the number of parents as it makes a good use of any available space.

Lens

The lens layout pushes highly-connected nodes into the center, and forces less connected nodes outwards. Due to its circular arrangement, the lens layout makes good use of the available space and generally creates networks that are denser than other layouts.

Lens is the default layout for arranging items inside open combos, but you can also use the concentric arrangement.

Coordinates

There are two ways of representing coordinates on the chart.

World Coordinates represent an absolute position within the chart, where 0, 0 is the center of the chart. They correspond exactly to the positions of a node.

When integrating ReGraph with Leaflet, world coordinates are represented as lng, lat rather than x, y positions.

View Coordinates represent a pixel position relative to the viewport, where 0, 0 is the top-left corner of the view. The x, y position of an event, such as onClick, is reported in view coordinates. View coordinates change whenever the user pans the view.

To convert between world and view coordinates, you can use the viewCoordinates and worldCoordinates instance methods.

import React from 'react';
import ReactDOM from 'react-dom';

import { Chart } from 'regraph';

import 'leaflet/dist/leaflet';
import 'leaflet/dist/leaflet.css';

const data = {
  a: {
    color: '#5fe3bf',
    label: {
      text: 'a',
      color: 'rgb(61, 72, 82)',
      backgroundColor: 'rgba(0,0,0,0)',
    },
    coordinates: { lat: 33.942536, lng: -118.408075 },
  },
  b: {
    color: '#5fe3bf',
    label: {
      text: 'b',
      color: 'rgb(61, 72, 82)',
      backgroundColor: 'rgba(0,0,0,0)',
    },
    coordinates: { lat: 32.847111, lng: -96.851778 },
  },
  c: {
    color: '#5fe3bf',
    label: {
      text: 'c',
      color: 'rgb(61, 72, 82)',
      backgroundColor: 'rgba(0,0,0,0)',
    },
    coordinates: { lat: 40.777245, lng: -73.872608 },
  },
  d: {
    color: '#5fe3bf',
    label: {
      text: 'd',
      color: 'rgb(61, 72, 82)',
      backgroundColor: 'rgba(0,0,0,0)',
    },
    coordinates: { lat: 47.449, lng: -122.309306 },
  },
};

const defaultState = {
  selected: '',
  view: ' -, -',
  world: ' -, -',
};

export default function Coordinates() {
  const [positions, setPositions] = React.useState({});
  const [state, setState] = React.useState({
    ...defaultState,
    map: false,
    layout: { packing: 'rectangle' },
  });
  const chartRef = React.createRef(null);

  const onChangeHandler = (change) => {
    const { selected } = state;
    if (change.view) {
      handleUpdate(selected);
    }
    if (change.selection) {
      handleUpdate(Object.keys(change.selection)[0]);
    }
    if (change.positions) {
      setPositions(change.positions);
      handleUpdate(selected);
    }
  };

  const handleUpdate = (id) => {
    setState((current) => {
      const { map } = current;
      const update = { ...defaultState, map, selected: id };
      if (id) {
        let worldx;
        let worldy;
        if (map) {
          const { lng, lat } = data[id].coordinates;
          worldx = lng;
          worldy = lat;
        } else {
          const { x, y } = positions[id];
          worldx = x;
          worldy = y;
        }
        const { x: viewx, y: viewy } = chartRef.current.viewCoordinates(worldx, worldy);
        update.world = ` ${Math.round(worldx)}, ${Math.round(worldy)}`;
        update.view = ` ${Math.round(viewx)}, ${Math.round(viewy)}`;
      }
      return update;
    });
  };

  const { view, world, map, layout } = state;
  const settings = {
    options: {
      navigation: false,
      overview: false,
      backgroundColor: 'rgb(61, 72, 82)',
    },
    onWheel: ({ preventDefault }) => {
      preventDefault();
    },
  };
  const panelStyle = {
    position: 'absolute',
    right: '0',
    bottom: '0',
    backgroundColor: 'hsl(211, 12%, 43%)',
    margin: '8px',
    padding: '8px 12px',
    zIndex: '1001',
    color: 'hsl(210, 16%, 82%)',
  };
  const labelStyle = {
    position: 'absolute',
    left: '0',
    top: '0',
    backgroundColor: 'hsl(211, 12%, 43%)',
    margin: '8px',
    padding: '8px 12px',
    zIndex: '1001',
    color: 'hsl(210, 16%, 82%)',
  };
  const inputStyle = {
    width: 'auto',
  };
  return (
    <div style={{ position: 'relative', height: '99%' }}>
      <Chart
        items={data}
        ref={chartRef}
        onChange={(evt) => {
          onChangeHandler(evt);
        }}
        map={map}
        layout={layout}
        {...settings}
      />
      <label style={labelStyle}>
        <input
          type="checkbox"
          checked={map}
          style={inputStyle}
          onChange={() =>
            setState((current) => {
              return { ...current, map: !map };
            })
          }
        />
        Show Map
      </label>
      <div style={panelStyle}>
        <b>Coordinates</b>
        <div>
          View (x/y):
          {view}
        </div>
        <div>
          World ({map ? 'lng/lat' : 'x/y'}):
          {world}
        </div>
      </div>
    </div>
  );
}

ReactDOM.render(<Coordinates />, document.getElementById('app'));

Loading Chart

Re-rendering in ReGraph

State management in ReGraph relies on immutability, a concept where a prop cannot be changed (mutated) directly once it's created, but it can be updated by replacing it with a new prop. On every render, ReGraph uses referential equality to decide whether any props have changed.

Whenever a new object is passed as a prop, ReGraph assumes something has changed and performs a re-render. If the same object is passed, ReGraph assumes nothing has changed. This is why ReGraph can quickly and efficiently respond to re-renders even in very large datasets.

To prevent unnecessary re-renders, applications must be disciplined in how props are updated. For example, passing a new object with identical property values into the layout prop will trigger a re-render that may change the positions of nodes.

If you want to change a sub-property on a prop that's an object (e.g. the items prop or others), you need to create a whole new object to make sure that ReGraph performs a re-render.

Consider the following object in the items prop:

items: {
  n1: {
    label: {
      color: 'blue', // <-- User changes a node's label color
      text: 'node 1'
    }
  },
  n2: {
    label: {
      text: 'node 2'
    } 
  }
}

Let's say we change the n1's label.color property. If we simply mutate the n1 object and pass it into the items prop, the change won't be recognized and our chart will stay the same.

To correctly render the change, we have to create new objects for items and n1, and set a new value for color. You can see the properties that need to be re‑created marked with a star below:

items*: {
  n1*: {
    label*: {
      color*: 'red',
      text: 'node1'
    }
  },
  n2: {
    label: {
      text: 'node 2'
    }
  }
}

Deep cloning creates a copy of all the object values, and all the values of all the nested objects within it. In comparison, shallow cloning would create copies of primitive values, but objects wouldn't be copied, only referenced, which would not be recognized during a re-render in ReGraph.

Let's use the example above to illustrate the difference between the two cloning techniques. You may choose to use object destructuring to create a new object that you can modify and pass back to ReGraph:

const shallowClone={...items}
shallowClone.a.color='red'
setItems(shallowClone) // doesn't work

This doesn't work as shallowClone.a equals items.a. The shallowClone.a is just a reference to items.a and ReGraph decides not to do a re‑render as, apparently, nothing has changed.

This is what you would need to do instead:

const deepClone = window.structuredClone(items)
deepClone.a.color= 'red'
setItems(deepClone) // works

This does work as deepClone.a does not equal items.a and ReGraph will re‑render. See this playground that shows both techniques.

Using object destructuring is possible, but you need to make sure that you don't accidentally pass any references to old objects. Here is an example of how to successfully do this:

// Clone the items object before making any changes
const newItems = Object.assign({}, this.state.items);

// Deep clone and update the item you want to change.
// If you're using spread operator, access nested properties
// to deep clone nested changes as well
const newItem = Object.assign({}, newItems.n1, {
  label: {
    ...newItems.n1.label,
    color: 'red'
  }
});

// Write the change back to the newItems object
newItems.n1 = newItem;

// Update app state and trigger a re-render
this.setState({ items: newItems });

Using deep cloning and immutability in your application code provides better performance, results in fewer unexpected side-effects, and lets you rewind or undo user actions. We use these patterns throughout our stories.

Chart Animation

When you pass a new state to the chart, ReGraph will calculate any differences between the new and existing states and animate the changes. The result is new nodes moving smoothly in and out of the chart from sensible origins, and layouts and property changes animating to let the end user follow the changes on-screen.

On any given update, ReGraph decides what animations are required and builds a queue of changes. It will then animate those changes in series until the Chart is in the right place. If state changes occur during animation, ReGraph will simply add more changes to the animation queue.

Animation should be switched off during drag events to ensure the drag is able to complete before any associated animations are run; see the Combos Drag and Drop story.

Duration

You can control the speed of animation via the animation prop. Passing a time value tells ReGraph how long it should take to animate each state update (in milliseconds). This time will be shared by whatever animations are required. So if ReGraph has 1000ms to animate new items being loaded into the chart, a layout which repositions nodes, and a change to node size, then each animation will run in about a third of a second.

The example below uses setInterval to add a new item to the chart every two seconds, triggering an animated layout.

import React, { useState, useEffect } from 'react';
import ReactDOM from 'react-dom';

import { Chart } from 'regraph';

const nodes = {
  center: {
    color: 'rgb(241, 93, 91)',
  },
};
const links = {};
for (let i = 1; i < 9; i += 1) {
  nodes[i] = {
    color: '#5fe3bf',
  };
  links[`link-${i}`] = {
    id1: 'center',
    id2: i,
    width: 3,
    end1: {
      color: 'rgb(241, 93, 91)',
    },
    end2: {
      color: '#5fe3bf',
    },
  };
}

export default function Animation() {
  const [state, setState] = useState({
    step: 9,
    items: {},
  });

  // configure animation setup and cleanup
  useEffect(() => {
    const updateNodes = () => {
      setState((current) => {
        if (current.step > 8) {
          const initial = {
            center: {
              ...nodes.center,
            },
            ...links,
          };
          return {
            step: 1,
            items: initial,
          };
        }
        const update = { ...current.items };
        update[current.step] = nodes[current.step];
        return {
          step: current.step + 1,
          items: update,
        };
      });
    };
    const animLoop = setInterval(updateNodes, 2000);
    return () => {
      clearInterval(animLoop);
    };
  }, []);

  const onWheelHandler = ({ preventDefault }) => {
    preventDefault();
  };

  const { items } = state;
  const animation = {
    time: 1000,
  };
  return (
    <Chart
      items={items}
      animation={animation}
      layout={{
        name: 'organic',
        fixed: ['center'],
      }}
      onWheel={onWheelHandler}
      options={{
        navigation: false,
        overview: false,
        backgroundColor: 'rgb(61, 72, 82)',
      }}
    />
  );
}

ReactDOM.render(<Animation />, document.getElementById('app'));

Loading Chart

Instance Methods

We expose additional methods on chart objects, which are available when you have a reference to an instance of a chart. Refs provide a way to access React elements created in the render method. For example, when you have a ref to a chart, you can call the ping method which will ping the clicked items in the chart. For all instance methods, see the API Reference.

const MyFunctionalComponent = (props) => {
  const { items } = props;
  const chartRef = React.useRef(null);

  const ping = ({ id }) => {
    if (id) {
      chartRef.current.ping({ [id]: true });
    }
  };

  return (
    <Chart
      ref={chartRef}
      items={items}
      positions={positions}
      onClick={ping} />
  );
};

Chart Export

The export instance method generates a static image of the chart (or its current view) in PNG, JPG, SVG or PDF:

const MyFunctionalComponent = (props) => {
  const { items } = props;
  const chartRef = React.useRef(null);

  const downloadImage = () => {
    chartRef.current.export({ type: 'svg' }).then((exportedImage) => {
      exportedImage.download('regraph_image');
    });
  };

  return (
    <>
      <Chart ref={chartRef} items={items} />
      <button onClick={downloadImage}>
        Download image
      </button>
    </>
  );
};

The Export story shows how to get started with export.

For PNG and JPG, the maximum resolution that can be exported depends on the device/OS/browser and available memory. For all formats, the maximum size of the output should not exceed 100 megapixels.

If you are exporting into SVG and your charts include multiple different SVG images, make sure that SVG elements such as mask or pattern that have id property specified do not use duplicate ids between different SVG images.

Right-to-Left Text

ReGraph supports multiple languages, including right-to-left (RTL) and bidirectional (BIDI) writing systems such as Arabic and Hebrew.

When RTL characters are detected, ReGraph applies RTL auto support by default. This is a reliable approach for a large scope of cases including:

• Mixed-system texts with both LTR and RTL characters
• Texts containing punctuation, numbers, emojis or other special characters
• Strings with symbols in strict functional order such as e-mail addresses or URLs

See the Right to Left Text story to see RTL auto support in action.

If you wish to always reverse the order of the whole text, or if you have specific requirements for more complex cases, you can use forced RTL mode:

<Chart dir="rtl" />

You can also use control characters in the label text to embed a specific direction.

For more details on using control characters, see How to use Unicode controls for bidi text (W3C documentation). Note that this page references isolated control characters, which ReGraph doesn't support.

Leaflet Integration

You can use ReGraph with Leaflet.js to visualize and analyze geospatial data on a map.

While Leaflet provides a map to use as a background, ReGraph lays out the chart onto the map according to the latitude and longitude locations of nodes.

To integrate ReGraph with Leaflet, you must add Leaflet version 1.9.x to your project and import it into your app.

To display the map, set the map prop:

import React from 'react';
import ReactDOM from 'react-dom';

import { Chart } from 'regraph';

import 'leaflet/dist/leaflet';
import 'leaflet/dist/leaflet.css';

const settings = {
  options: {
    navigation: false,
  },
  animation: { time: 0 },
  onChange: ({ leaflet }) => {
    if (leaflet) {
      leaflet.scrollWheelZoom.disable();
    }
  },
};

export default function Map() {
  const items = {
    la: {
      coordinates: { lat: 33.9, lng: -118.4 },
      color: 'rgb(7, 156, 131)',
    },
    dallas: {
      coordinates: { lat: 32.8, lng: -96.8 },
      color: 'rgb(7, 156, 131)',
    },
    link: {
      id1: 'la',
      id2: 'dallas',
      width: 4,
      color: 'rgb(7, 156, 131)',
    },
  };

  return <Chart items={items} map {...settings} />;
}

ReactDOM.render(<Map />, document.getElementById('app'));

Loading Chart

ReGraph uses OpenStreetMap as a default map tile provider.

When the map is displayed, there are some important behavioral differences in the chart:

• Nodes are positioned by lat and lng in coordinates. The positions prop is ignored.
• Nodes without both lat and lng specified are hidden.
• The worldCoordinates method returns an object with lat and lng properties.
• Annotations are hidden as they are not supported.
• Links are always shown as direct links. See Link Shapes for details.
• Open combos are not supported.