跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

neo4j-nvl-skill

Neo4j Visualization Library (NVL) — framework-agnostic graph rendering for the browser.

neo4j-contrib · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add neo4j-contrib/neo4j-skills --skill neo4j-nvl-skill

技能说明


name: neo4j-nvl-skill description: Neo4j Visualization Library (NVL) — framework-agnostic graph rendering for the browser. Covers @neo4j-nvl/base (NVL class, nodes/relationships, Canvas vs WebGL renderer), @neo4j-nvl/interaction-handlers (ZoomInteraction, PanInteraction, DragNodeInteraction, ClickInteraction, HoverInteraction, BoxSelectInteraction, LassoInteraction, KeyboardInteraction), and @neo4j-nvl/react (InteractiveNvlWrapper, BasicNvlWrapper, StaticPictureWrapper). Use when rendering a Neo4j graph in a browser, feeding driver results through nvlResultTransformer, choosing Canvas vs WebGL, wiring node/relationship click/hover/drag handlers, or embedding NVL in React, Vite, or vanilla JS apps. Does NOT handle Cypher query authoring — use neo4j-cypher-skill. Does NOT handle driver lifecycle, sessions, or executeQuery setup — use neo4j-driver-javascript-skill. Does NOT handle GraphVisualization/Needle default embed — use @neo4j-ndl/react. compatibility: "@neo4j-nvl packages 2.0.x; React 19 for @neo4j-nvl/react; modern browsers with Canvas2D + WebGL2" version: 2.0.0 allowed-tools: Bash WebFetch

When to Use

  • Rendering a Neo4j graph in a browser (vanilla JS, React, Vite) with custom interactions, rendering, or data shapes
  • Visualizing driver.executeQuery results as an interactive graph
  • Wiring zoom, pan, drag, click, hover, lasso, or box-select interactions
  • Embedding NVL inside an existing app and synchronizing graph state

When NOT to Use

  • Pre-styled embedded graph view with default behavior, no custom interactions → GraphVisualization from @neo4j-ndl/react (Neo4j Needle / NDL design system) — wraps NVL with default Neo4j styling. See Use NVL or the Needle Component? below.
  • Python / Jupyter notebook graph visualization → neo4j/python-graph-visualization (the Python port of NVL)
  • Writing/optimizing Cypher → neo4j-cypher-skill
  • Driver setup / executeQuery / sessions → neo4j-driver-javascript-skill
  • Server-side data fetching with no rendering → neo4j-driver-javascript-skill
  • GDS algorithm execution → neo4j-gds-skill or neo4j-aura-graph-analytics-skill
  • GraphQL API → neo4j-graphql-skill

Use NVL or the Needle Component?

NeedUse
Embed a graph view with default Neo4j styling, no custom interactions or renderingGraphVisualization from @neo4j-ndl/react (Neo4j Needle / NDL design system) — wraps NVL and accepts records shaped { id, labels, properties: { key: { stringified, type } } } (NeoNode)
Custom interactions, custom rendering, non-standard data shapes, or framework-agnostic embeddingThis skill — use NVL directly

If the answer is the first row, install and use the Needle component instead of NVL — do not duplicate styling work.


Install

npm install @neo4j-nvl/base                  # core (required)
npm install @neo4j-nvl/interaction-handlers  # standard interactions (optional, vanilla JS)
npm install @neo4j-nvl/react                 # React wrappers (optional)

Peer requirements: React 19 for @neo4j-nvl/react. The published peerDependency range still permits React 18, but mixing major versions is not recommended — target 19. @neo4j-nvl/layout-workers is a transitive dependency — never install directly. neo4j-driver is a peer of @neo4j-nvl/base only when using nvlResultTransformer.

Starter templates: https://github.com/neo4j-devtools/nvl-boilerplates — official per-framework scaffolds; prefer these over hand-rolled setups.

License: NVL ships under the Neo4j Visualization Library License — for use with Neo4j products only. Cannot be used against other graph backends.


Pick the Right Paradigm

NeedUse
React app, default interactions<InteractiveNvlWrapper> from @neo4j-nvl/react
React app, custom interaction wiring<BasicNvlWrapper> + own handlers via ref
Vanilla JS, standard interactionsNVL + @neo4j-nvl/interaction-handlers
Vanilla JS, fully custom event logicNVL + container.addEventListener + nvl.getHits()
Static PNG/SVG image export<StaticPictureWrapper> or nvl.saveToFile() / nvl.saveToSvg()

Pick the Right Renderer

RendererMax nodesDetailUse case
'canvas' (default)~1,000Captions, icons, arrows, pixel-perfect hit-testingDetail investigation, small graphs
'webgl'100,000+No captions; supports node icons and relationship arrowheads in 2.0Large-scale pattern exploration
const nvl = new NVL(container, nodes, rels, { renderer: 'webgl' })
nvl.setRenderer('canvas')   // swap at runtime

NVL 2.0 requires WebGL2 for the GPU renderer and force-directed physics engine. When GPU acceleration is unavailable, NVL can fall back to Canvas rendering and non-GPU layout implementations; use disableWebGL: true to explicitly avoid WebGL.


Container Setup

The container must have an explicit width AND height. Missing height → container collapses to 0 → graph invisible. Most-reported NVL bug.

<!-- ❌ height defaults to 0; graph invisible -->
<div id="viz"></div>

<!-- ✅ explicit dimensions -->
<div id="viz" style="width: 100%; height: 600px;"></div>

Vanilla — Base Library

import { NVL } from '@neo4j-nvl/base'

const container = document.getElementById('viz')
const nodes = [{ id: '1' }, { id: '2' }]
const relationships = [{ id: '12', from: '1', to: '2', type: 'KNOWS' }]

const nvl = new NVL(container, nodes, relationships)

With options + callbacks:

import { NVL } from '@neo4j-nvl/base'

const options = {
  initialZoom: 1.0,
  minZoom: 0.1,
  maxZoom: 8,
  layout: 'forceDirected',
  renderer: 'canvas',
  styling: { defaultNodeColor: '#0e86d4', defaultRelationshipColor: '#888' }
}
const callbacks = {
  onInitialization: () => console.log('NVL ready'),
  onLayo
阅读完整来源 ↗