@neo4j-nvl/react

Neo4j Visualization Library

Welcome to the Neo4j Visualization Library, NVL for short. NVL is a collection of libraries that can be used to build custom graph visualizations like those used in Neo4j Bloom and Explore(powered by Bloom). NVL is written in TypeScript and can be used in any JavaScript project. This package contains React components that make it easier to use NVL within a React application. If you want to use NVL with a framework other than React or want to build your own React wrapper, you can do so by using the NVL base library.

Consuming the library

Installing the library

You can install the NVL React wrappers with your preferred package manager, for example

npm install @neo4j-nvl/react

Using the library

This is an example on how to use the BasicReactWrapper component:

<BasicNvlWrapper nodes={nodes} rels={relationships} nvlOptions={options} nvlCallbacks={callbacks} />

When nodes and/or relationships are updated in the React wrapper, the NVL instance will be updated accordingly:

const [nodes, setNodes] = useState<Node[]>([{ id: '0' }, { id: '1' }])

const addElements = () => {
  const newNodes = [...nodes, { id: nodes.length }]
  setNodes(newNodes)
}

;<div>
  <BasicNvlWrapper nodes={nodes} />
  <button onClick={addElements}>Add Graph Elements</button>
</div>

If you want to access the NVL class outside of the React wrapper you can use a reference of NVL to call its methods:

const nvlRef = useRef<NVL>()

<div>
  <BasicNvlWrapper
    nodes={[{ id: '0' }, { id: '1' }]}
    rels={[{ from: '0', to: '1', id: '10' }]}
    ref={nvlRef}
  />
  <button onClick={() => nvlRef.current?.zoomToNodes([0, 1])}>Zoom to Nodes</button>
</div>

To easily add common graph interaction, you can make use of the interaction handlers module and the InteractiveNvlWrapper.

The InteractiveNvlWrapper is a wrapper component that provides a basic set of interactions for the NVL. It is an extension of the BasicNvlWrapper component and incorporates the interaction handlers to provide a set of interaction events.

Events can be turned on and off by passing a callback function or a boolean value to the mouseEventCallbacks prop. The callback function will be called with the event's arguments when the event is triggered. If a boolean value is passed, the event will be turned on or off accordingly.

const [multiSelect, setMultiSelect] = useState(false)
<>
  <button onClick={() => setMultiSelect(!multiSelect)}>
    {multiSelect ? 'Disable' : 'Enable'} multi-select
  </button>
  <InteractiveNvlWrapper
    nodes={nodes}
    rels={relationships}
    mouseEventCallbacks={{
      onHover: (element) => console.log(element),
      onNodeClick: (node) => console.log(node),
      onMultiSelect: multiSelect
   }}
  />
</>

You can also find more instructions and examples on how to use the NVL React wrappers in the docs.

Product analytics

In order to improve the library we are collecting some information about the usage of NVL. If you prefer to disable this behavior setting disableTelemetry to true in the nvlOptions property. For example:

<BasicNvlWrapper
  nvlOptions={{ disableTelemetry: true }}
  nodes={[{ id: '0' }, { id: '1' }]}
  rels={[{ from: '0', to: '1', id: '10' }]}
/>