@neo4j-nvl/react 1.2.1 → 2.0.0

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to NVL will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [2.0.0] - 2026-09-11
+
+This 2.0.0 major release upgrades NVL to WebGL2 for both the renderer and physics engine, unlocking major performance improvements. It also adds new clustering capabilities with visual decorations to the force directed and hierarchical layouts.
+
+### Added
+
+* `clusterBy` layout option for both force-directed and hierarchical layouts.
+* Cluster interaction API for handling events on clustered elements.
+* Support for rendering icons and arrowheads in the WebGL renderer.
+* Configurable minimum and maximum FPS caps for the rendering loop.
+* Circle seeding option for the physics layout.
+
+### Changed
+
+* Upgraded the WebGL renderer and physics engine to use WebGL2.
+* Migrated the hierarchical layout engine dependency to `@dagrejs/dagre` 3.1.1.
+* Greatly optimized physics layout performance and stabalisation speed.
+* Improved rendering performance.
+
+### Fixed
+
+* Added safety guards to harden the renderer against missing X/Y coordinate data.
+
+### Removed
+
+* **BREAKING:** Removed deprecated Cytoscape support settings.
+* **BREAKING:** Removed deprecated standalone `layout` and `layoutOptions` props from the React wrappers in favour of the same props inside `NvlOptions`.
+* **BREAKING:** Removed deprecated `intelWorkaround` layout setting APIs.
+* **BREAKING:** Removed deprecated `onZoom` callback in favour of `onZoomAndPan`.
+
+## [1.2.2] - 2026-09-11
+
+This 1.2.2 patch release adds migration warnings for breaking changes planned for the next major release.
+
+### Added
+* `styling.overlayLineColor` for overlay UI stroke color (e.g. minimap viewport box).
+* Note in documentation on changes to client/screen coordinates on `NVL.getNodes()` and `onLayoutStep` `x`/`y`, moving screen coordinates to `clientPosition`.
+
+### Deprecated
+* `styling.minimapViewportBoxColor` in favour of `styling.overlayLineColor` (old option still works as a fallback).
+* `ForceDirectedOptions.intelWorkaround` (upgrade to WebGL2 in the next major release removes the need for it).
+* Top-level React wrapper `layout` / `layoutOptions` props in favour of `nvlOptions.layout` / `nvlOptions.layoutOptions`.
+
 ## [1.2.1] - 2026-07-28
 
 This 1.2.1 patch release contains several fixes and accessibility improvements.

package/README.md

@@ -47,7 +47,7 @@ const nvlRef = useRef<NVL>()
     rels={[{ from: '0', to: '1', id: '10' }]}
     ref={nvlRef}
   />
-  <button onClick={() => nvlRef.current?.zoomToNodes([0, 1])}>Zoom to Nodes</button>
+  <button onClick={() => nvlRef.current?.fit(['0', '1'])}>Zoom to Nodes</button>
 </div>
 ```
 
@@ -59,18 +59,18 @@ Events can be turned on and off by passing a callback function or a boolean valu
 `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)
+const [boxSelect, setBoxSelect] = useState(false)
 <>
-  <button onClick={() => setMultiSelect(!multiSelect)}>
-    {multiSelect ? 'Disable' : 'Enable'} multi-select
+  <button onClick={() => setBoxSelect(!boxSelect)}>
+    {boxSelect ? 'Disable' : 'Enable'} box select
   </button>
   <InteractiveNvlWrapper
     nodes={nodes}
     rels={relationships}
     mouseEventCallbacks={{
-      onHover: (element) => console.log(element),
+      onHover: (element, hitElements) => console.log(element, hitElements),
       onNodeClick: (node) => console.log(node),
-      onMultiSelect: multiSelect
+      onBoxSelect: boxSelect
    }}
   />
 </>

package/lib/__tests__/BasicNvlWrapper.test.js

@@ -27,8 +27,12 @@ describe('BasicNvlWrapper', () => {
     });
     test('initialises NVL expectedly with a graph object and properties', () => {
         const mockLayoutDoneFunction = jest.fn();
-        render(_jsx("div", { children: _jsx(BasicNvlWrapper, { nodes: [{ id: '1' }, { id: '2' }], rels: [{ id: '12', from: '1', to: '2' }], layout: HierarchicalLayoutType, layoutOptions: { enableCytoscape: true }, nvlOptions: { renderer: 'canvas' }, nvlCallbacks: { onLayoutDone: mockLayoutDoneFunction } }) }));
-        expect(NVL).toHaveBeenCalledWith(expect.any(HTMLDivElement), [{ id: '1' }, { id: '2' }], [{ id: '12', from: '1', to: '2' }], { renderer: 'canvas', layout: HierarchicalLayoutType, layoutOptions: { enableCytoscape: true } }, {
+        render(_jsx("div", { children: _jsx(BasicNvlWrapper, { nodes: [{ id: '1' }, { id: '2' }], rels: [{ id: '12', from: '1', to: '2' }], nvlOptions: {
+                    renderer: 'canvas',
+                    layout: HierarchicalLayoutType,
+                    layoutOptions: { direction: 'down' }
+                }, nvlCallbacks: { onLayoutDone: mockLayoutDoneFunction } }) }));
+        expect(NVL).toHaveBeenCalledWith(expect.any(HTMLDivElement), [{ id: '1' }, { id: '2' }], [{ id: '12', from: '1', to: '2' }], { renderer: 'canvas', layout: HierarchicalLayoutType, layoutOptions: { direction: 'down' } }, {
             onLayoutDone: mockLayoutDoneFunction
         });
     });
@@ -132,4 +136,24 @@ describe('BasicNvlWrapper', () => {
         expect(setZoomAndPan).toHaveBeenCalledTimes(1);
         expect(setZoom).not.toHaveBeenCalled();
     });
+    test('calls setLayout when nvlOptions.layout changes', () => {
+        const setLayout = jest.fn();
+        jest.spyOn(NVL.prototype, 'setLayout').mockImplementation(setLayout);
+        const { rerender } = render(_jsx("div", { children: _jsx(BasicNvlWrapper, { nodes: [], rels: [], nvlOptions: { layout: HierarchicalLayoutType } }) }));
+        expect(setLayout).toHaveBeenCalledWith(HierarchicalLayoutType);
+        expect(setLayout).toHaveBeenCalledTimes(1);
+        rerender(_jsx("div", { children: _jsx(BasicNvlWrapper, { nodes: [], rels: [], nvlOptions: { layout: 'forceDirected' } }) }));
+        expect(setLayout).toHaveBeenCalledWith('forceDirected');
+        expect(setLayout).toHaveBeenCalledTimes(2);
+    });
+    test('calls setLayoutOptions when nvlOptions.layoutOptions changes', () => {
+        const setLayoutOptions = jest.fn();
+        jest.spyOn(NVL.prototype, 'setLayoutOptions').mockImplementation(setLayoutOptions);
+        const { rerender } = render(_jsx("div", { children: _jsx(BasicNvlWrapper, { nodes: [], rels: [], nvlOptions: { layoutOptions: { direction: 'down' } } }) }));
+        expect(setLayoutOptions).toHaveBeenCalledWith({ direction: 'down' });
+        expect(setLayoutOptions).toHaveBeenCalledTimes(1);
+        rerender(_jsx("div", { children: _jsx(BasicNvlWrapper, { nodes: [], rels: [], nvlOptions: { layoutOptions: { direction: 'up' } } }) }));
+        expect(setLayoutOptions).toHaveBeenCalledWith({ direction: 'up' });
+        expect(setLayoutOptions).toHaveBeenCalledTimes(2);
+    });
 });

package/lib/__tests__/InteractiveNvlWrapper.test.js

@@ -85,11 +85,15 @@ describe('InteractiveNvlWrapper', () => {
     });
     test('initialises NVL expectedly with a graph object and properties', () => {
         const mockLayoutDoneFunction = jest.fn();
-        render(_jsx(InteractiveNvlWrapper, { nodes: [{ id: '1' }, { id: '2' }], rels: [{ id: '12', from: '1', to: '2' }], layout: HierarchicalLayoutType, layoutOptions: { enableCytoscape: true }, nvlOptions: { renderer: 'canvas' }, nvlCallbacks: { onLayoutDone: mockLayoutDoneFunction } }));
+        render(_jsx(InteractiveNvlWrapper, { nodes: [{ id: '1' }, { id: '2' }], rels: [{ id: '12', from: '1', to: '2' }], nvlOptions: {
+                renderer: 'canvas',
+                layout: HierarchicalLayoutType,
+                layoutOptions: { direction: 'down' }
+            }, nvlCallbacks: { onLayoutDone: mockLayoutDoneFunction } }));
         act(() => {
             mockOnInitialization?.();
         });
-        expect(NVL).toHaveBeenCalledWith(expect.any(HTMLDivElement), [{ id: '1' }, { id: '2' }], [{ id: '12', from: '1', to: '2' }], { renderer: 'canvas', layout: HierarchicalLayoutType, layoutOptions: { enableCytoscape: true } }, {
+        expect(NVL).toHaveBeenCalledWith(expect.any(HTMLDivElement), [{ id: '1' }, { id: '2' }], [{ id: '12', from: '1', to: '2' }], { renderer: 'canvas', layout: HierarchicalLayoutType, layoutOptions: { direction: 'down' } }, {
             onLayoutDone: mockLayoutDoneFunction,
             onInitialization: mockOnInitialization
         });
@@ -187,7 +191,7 @@ describe('InteractiveNvlWrapper', () => {
         {
             name: 'ZoomInteraction',
             InteractionClass: ZoomInteraction,
-            callback: { onZoom: jest.fn() },
+            callback: { onZoomAndPan: jest.fn() },
             options: {}
         },
         {

package/lib/basic-wrapper/BasicNvlWrapper.d.ts

@@ -1,4 +1,4 @@
-import type { ExternalCallbacks, Layout, LayoutOptions, Node, NvlOptions, Relationship } from '@neo4j-nvl/base';
+import type { ExternalCallbacks, Node, NvlOptions, Relationship } from '@neo4j-nvl/base';
 import NVL from '@neo4j-nvl/base';
 import { type HTMLProps } from 'react';
 /**
@@ -9,16 +9,6 @@ export interface BasicReactWrapperProps {
     nodes: Node[];
     /** The rels of the graph of type Relationship[] */
     rels: Relationship[];
-    /**
-     * The layout, can be 'forceDirected' or 'hierarchical'
-     * @deprecated Use the layout property in nvlOptions instead. This property will be removed in a future version.
-     */
-    layout?: Layout;
-    /**
-     * Options for the current layout
-     * @deprecated Use the layoutOptions property in nvlOptions instead. This property will be removed in a future version.
-     */
-    layoutOptions?: LayoutOptions;
     /** an Object containing functions for callbacks on certain actions */
     nvlCallbacks?: ExternalCallbacks;
     /** An object containing options for the Nvl instance */

package/lib/basic-wrapper/BasicNvlWrapper.js

@@ -12,7 +12,7 @@ import { useDeepCompareEffect } from '../utils/hooks';
  *
  * For examples, head to the {@link https://neo4j.com/docs/nvl/current/react-wrappers/#_basic_react_wrapper Basic React wrapper documentation page}.
  */
-export const BasicNvlWrapper = memo(forwardRef(({ nodes, rels, layout, layoutOptions, nvlCallbacks = {}, nvlOptions = {}, positions = [], zoom, pan, onInitializationError, ...nvlEvents }, ref) => {
+export const BasicNvlWrapper = memo(forwardRef(({ nodes, rels, nvlCallbacks = {}, nvlOptions = {}, positions = [], zoom, pan, onInitializationError, ...nvlEvents }, ref) => {
     const nvlRef = useRef(null);
     const prevZoomRef = useRef(undefined);
     const prevPanRef = useRef(undefined);
@@ -47,12 +47,8 @@ export const BasicNvlWrapper = memo(forwardRef(({ nodes, rels, layout, layoutOpt
         const mainContainerIsReady = containerRef.current !== null;
         if (mainContainerIsReady && minimapContainerIsReady) {
             if (nvlRef.current === null) {
-                const combinedOptions = { ...nvlOptions, layoutOptions };
-                if (layout !== undefined) {
-                    combinedOptions.layout = layout;
-                }
                 try {
-                    newNvl = new NVL(containerRef.current, currentNodes, currentRels, combinedOptions, nvlCallbacks);
+                    newNvl = new NVL(containerRef.current, currentNodes, currentRels, nvlOptions, nvlCallbacks);
                     nvlRef.current = newNvl;
                     setCurrentRels(rels);
                     setCurrentNodes(nodes);
@@ -96,19 +92,17 @@ export const BasicNvlWrapper = memo(forwardRef(({ nodes, rels, layout, layoutOpt
         nvlRef.current.removeNodesWithIds(nodesToRemove);
     }, [currentNodes, currentRels, nodes, rels]);
     useEffect(() => {
-        const updatedLayout = layout ?? nvlOptions.layout;
-        if (nvlRef.current === null || updatedLayout === undefined) {
+        if (nvlRef.current === null || nvlOptions.layout === undefined) {
             return;
         }
-        nvlRef.current.setLayout(updatedLayout);
-    }, [layout, nvlOptions.layout]);
+        nvlRef.current.setLayout(nvlOptions.layout);
+    }, [nvlOptions.layout]);
     useDeepCompareEffect(() => {
-        const updatedLayoutOptions = layoutOptions ?? nvlOptions?.layoutOptions;
-        if (nvlRef.current === null || updatedLayoutOptions === undefined) {
+        if (nvlRef.current === null || nvlOptions.layoutOptions === undefined) {
             return;
         }
-        nvlRef.current.setLayoutOptions(updatedLayoutOptions);
-    }, [layoutOptions, nvlOptions.layoutOptions]);
+        nvlRef.current.setLayoutOptions(nvlOptions.layoutOptions);
+    }, [nvlOptions.layoutOptions]);
     useEffect(() => {
         if (nvlRef.current === null || nvlOptions.renderer === undefined) {
             return;

package/lib/interactive-nvl-wrapper/InteractionHandlers.js

@@ -21,8 +21,10 @@ export const InteractionHandlers = ({ nvlRef, mouseEventCallbacks, keyboardEvent
     useInteraction(ClickInteraction, clickInteraction, mouseEventCallbacks.onCanvasClick, 'onCanvasClick', nvlRef, interactionOptions);
     useInteraction(ClickInteraction, clickInteraction, mouseEventCallbacks.onCanvasDoubleClick, 'onCanvasDoubleClick', nvlRef, interactionOptions);
     useInteraction(ClickInteraction, clickInteraction, mouseEventCallbacks.onCanvasRightClick, 'onCanvasRightClick', nvlRef, interactionOptions);
+    useInteraction(ClickInteraction, clickInteraction, mouseEventCallbacks.onClusterClick, 'onClusterClick', nvlRef, interactionOptions);
+    useInteraction(ClickInteraction, clickInteraction, mouseEventCallbacks.onClusterDoubleClick, 'onClusterDoubleClick', nvlRef, interactionOptions);
+    useInteraction(ClickInteraction, clickInteraction, mouseEventCallbacks.onClusterRightClick, 'onClusterRightClick', nvlRef, interactionOptions);
     useInteraction(PanInteraction, panInteraction, mouseEventCallbacks.onPan, 'onPan', nvlRef, interactionOptions);
-    useInteraction(ZoomInteraction, zoomInteraction, mouseEventCallbacks.onZoom, 'onZoom', nvlRef, interactionOptions);
     useInteraction(ZoomInteraction, zoomInteraction, mouseEventCallbacks.onZoomAndPan, 'onZoomAndPan', nvlRef, interactionOptions);
     useInteraction(DragNodeInteraction, dragNodeInteraction, mouseEventCallbacks.onDrag, 'onDrag', nvlRef, interactionOptions);
     useInteraction(DragNodeInteraction, dragNodeInteraction, mouseEventCallbacks.onDragStart, 'onDragStart', nvlRef, interactionOptions);

package/lib/interactive-nvl-wrapper/InteractiveNvlWrapper.d.ts

@@ -10,6 +10,6 @@ import type { InteractiveNvlWrapperProps } from './types';
  * The mouseEventCallbacks property takes an object where various callbacks can be defined
  * and behavior can be toggled on and off.
  *
- * For examples, head to the {@link https://neo4j.com/docs/nvl/current/react-wrappers/#_interactive_reactive_wrapperr Interactive React wrapper documentation page}.
+ * For examples, head to the {@link https://neo4j.com/docs/nvl/current/react-wrappers/#_interactive_react_wrapper Interactive React wrapper documentation page}.
  */
 export declare const InteractiveNvlWrapper: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<Omit<InteractiveNvlWrapperProps & HTMLProps<HTMLDivElement>, "ref"> & import("react").RefAttributes<NVL>>>;

package/lib/interactive-nvl-wrapper/InteractiveNvlWrapper.js

@@ -18,9 +18,9 @@ const options = {
  * The mouseEventCallbacks property takes an object where various callbacks can be defined
  * and behavior can be toggled on and off.
  *
- * For examples, head to the {@link https://neo4j.com/docs/nvl/current/react-wrappers/#_interactive_reactive_wrapperr Interactive React wrapper documentation page}.
+ * For examples, head to the {@link https://neo4j.com/docs/nvl/current/react-wrappers/#_interactive_react_wrapper Interactive React wrapper documentation page}.
  */
-export const InteractiveNvlWrapper = memo(forwardRef(({ nodes, rels, layout, layoutOptions, onInitializationError, mouseEventCallbacks = {}, keyboardEventCallbacks = {}, nvlCallbacks = {}, nvlOptions = {}, interactionOptions = options, ...nvlEvents }, nvlRef) => {
+export const InteractiveNvlWrapper = memo(forwardRef(({ nodes, rels, onInitializationError, mouseEventCallbacks = {}, keyboardEventCallbacks = {}, nvlCallbacks = {}, nvlOptions = {}, interactionOptions = options, ...nvlEvents }, nvlRef) => {
     const newNvlRef = useRef(null);
     const myNvlRef = nvlRef ?? newNvlRef;
     const [isNvlInitialized, setIsNvlInitialized] = useState(false);
@@ -42,5 +42,5 @@ export const InteractiveNvlWrapper = memo(forwardRef(({ nodes, rels, layout, lay
                         }
                         handleInitialization();
                     }
-                }, layout: layout, layoutOptions: layoutOptions, onInitializationError: handleInitializationError, ...nvlEvents }), setupInteractions && (_jsx(InteractionHandlers, { nvlRef: myNvlRef, mouseEventCallbacks: mouseEventCallbacks, keyboardEventCallbacks: keyboardEventCallbacks, interactionOptions: interactionOptions }))] }));
+                }, onInitializationError: handleInitializationError, ...nvlEvents }), setupInteractions && (_jsx(InteractionHandlers, { nvlRef: myNvlRef, mouseEventCallbacks: mouseEventCallbacks, keyboardEventCallbacks: keyboardEventCallbacks, interactionOptions: interactionOptions }))] }));
 }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neo4j-nvl/react",
-  "version": "1.2.1",
+  "version": "2.0.0",
   "main": "lib/index.js",
   "homepage": "https://neo4j.com/docs/nvl/current/",
   "license": "SEE LICENSE IN 'LICENSE.txt'",
@@ -36,8 +36,8 @@
     "react-dom": "19.2.1"
   },
   "dependencies": {
-    "@neo4j-nvl/base": "1.2.1",
-    "@neo4j-nvl/interaction-handlers": "1.2.1",
+    "@neo4j-nvl/base": "2.0.0",
+    "@neo4j-nvl/interaction-handlers": "2.0.0",
     "lodash": "4.18.1"
   },
   "peerDependencies": {