neo4j-nvl-skill

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?

Need	Use
Embed a graph view with default Neo4j styling, no custom interactions or rendering	GraphVisualization 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 embedding	This 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.