Using KeyLines with React

Step 2: Add KeyLines to the app

Download the KeyLines package from the link below and move it to the my-react-app directory.

In the terminal from my-react-app, add KeyLines as a package dependency:

npm install file:./keylines-8.6.0-11643712880.tgz

Step 3: Create a chart

First, update src/index.css to set the dimensions for the KeyLines chart:

html {
  box-sizing: border-box;
}

*, *:before, *:after {
  box-sizing: inherit;
}

body {
  margin: 0;
}

.chart-container {
  width: 100vw;
  height: 100vh;
}

Next, open the src/App.jsx file which contains the React component, and replace the contents of this file with a simple KeyLines React chart component:

import { Chart } from 'keylines/react';     // imports the KeyLines React chart component

const data = {               // declares chart data - a single node with a label
  type: 'LinkChart',         // A KeyLines Chart type - must be 'LinkChart'
    items: [
      { 
        type: 'node',
        id: 'n1', 
        c: '#43976C',        // node colour
        t: 'Hello World'     // node text label
      }
]};

function App() {                        // renders a chart
  let chart;            
  const changeChart = newChart => {     // saves a reference to the created KeyLines chart object
    chart = newChart;
  };

  return (
    <Chart
      data={data}                              // loads the data in required KeyLines format
      ready={changeChart}                      // calls the saved chart object
      containerClassName="chart-container"     // defines the container div for the chart
    />
  );
}

export default App;

The Chart component defined in src/react-keylines.jsx wraps the underlying KeyLines chart object.

The ready callback supplied to the component is called with the KeyLines chart object. Here the changeChart callback saves a reference to the KeyLines chart object.

You should now see a simple KeyLines chart in your browser:

Charts have a range of native options such as navigation to pan and zoom or overview window icon at the bottom right corner to toggle a chart overview.

Step 4: Add and parse the data

Replace the existing data object in src/App.jsx with this data:

const data = {
  person: [
    { name: 'Jenny', teamId: 1 },
    { name: 'Rosie', teamId: 0 },
    { name: 'Peter', teamId: 0 },
    { name: 'Sam', teamId: 1 },
  ],
  messages: [
    { from: 'Jenny', to: 'Sam', amount: 17 },
    { from: 'Sam', to: 'Jenny', amount: 12 },
    { from: 'Sam', to: 'Peter', amount: 1 },
    { from: 'Rosie', to: 'Jenny', amount: 2 },
    { from: 'Peter', to: 'Rosie', amount: 7 },
  ],
};

This dataset details messages between two teams of people.

KeyLines accepts a ChartData object, which defines an array of chart items and their attributes. This means that we will need to parse our raw data to a KeyLines chart object. This is how we've defined our data model:

• People are represented by nodes. Nodes require a type: 'node' and a unique id. The default node colour is transparent, so we will also set the c property.
• Messages between people are represented as links. Links require a type: 'link', a unique id, and id1 and id2 properties whose values are ids of nodes at each link end.

To parse the data, add this function inside the App() function:

function convertDataToKeyLinesFormat(data) {
  const items = [];

  data.person.forEach(({ name }) => {     // defines people as nodes
    items.push({
      id: name,
      type: 'node',
      c: '#43976C',
    });
  });

  data.messages.forEach(({ from, to }) => {     // defines messages as links
    items.push({
      type: 'link',
      id: `link_${from}_${to}`,
      id1: from,
      id2: to,
    });
  });

  return { type: 'LinkChart', items };        // adds 'LinkChart' required by KeyLines
}

And update the render function to return the parsed data:

return (
  <Chart
    data={convertDataToKeyLinesFormat(data)}  // loads the parsed data and runs the default layout
    ready={changeChart}
    containerClassName="chart-container"
  />
);

Note that react-keylines.jsx automatically performs a layout when loading new data. By default this is the organic layout, which is a versatile force-directed layout algorithm that is especially great for large datasets and complex networks, but there are also other layouts you can explore.

Your application and developer console should now be clear of any errors and you should see this network in the browser:

Our data model is now visualised as nodes and links, but it's difficult to distinguish the individual items on the chart. To address this, we will incorporate details as styling in the next step.

Step 8: Add foregrounding on selection

Now let's set a foregrounding behaviour that highlights the user-selected item and its immediate neighbours, which is particularly helpful for large charts with densely connected nodes.

Add a selection change handler function responding to a selection-change event to src/App.jsx after changeChart:

const selectionHandler = () => {
  const itemIds = chart.selection();
  const selectedItems = chart.getItem(itemIds); // Ensure we have clicked on a link or node, not the navigation control
  if (selectedItems.length !== 0) {
    const neighbours = chart.graph().neighbours(itemIds); // Foreground the selected item and its neighbours
    chart.foreground(
      (item) => itemIds.includes(item.id) || neighbours.nodes.includes(item.id)
    );
  } else {
    // Clicked on background - restore all items to the foreground
    chart.foreground(() => true);
  }
}

And in the render function, add the selection-change function that will attach the handler:

selection-change={selectionHandler}     // attaches the handler for selection-change event

The new selectionHandler function uses chart.getItem() to check whether the clicked id belongs to a node or a link in the chart.

If it does, then we use chart.graph().neighbours() to find the nodes connected to the clicked item, and then call chart.foreground() to put them in the foreground, and other chart items in the background.

If the user clicked on something else, such as the chart background, then we foreground all the chart items.