# 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)](https://neo4j.com/product/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](https://www.npmjs.com/package/@neo4j-nvl/base).

## Consuming the library

### Installing the library

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

```bash
npm install @neo4j-nvl/react
```

### Using the library

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

```tsx
<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:

```tsx
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:

```tsx
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.

```tsx
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](https://neo4j.com/docs/nvl/current/react-wrappers/).

### 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:

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

You can find more instructions and examples on how to use NVL interaction handlers in the [docs](https://neo4j.com/docs/nvl/current/react-wrappers/) and [API docs](https://neo4j.com/docs/api/nvl/current/modules/_neo4j_nvl_react.html), as well as in these [NVL code examples](https://neo4j.com/docs/api/nvl/current/examples.html?tab=react-vanilla).