@neo4j-nvl/react

Neo4j Visualization Library

Welcome to NVL (Neo4j Visualization Library). NVL is a collection of libraries that can be used to build custom graph visualizations like Neo4j Bloom. If you want to use NVL with a different framework than React or what to build your own React wrappers, 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.