Neo4j Nvl Skill

# neo4j-nvl-skill

Skill for the Neo4j Visualization Library (NVL) — covering:

- `@neo4j-nvl/base` — `NVL` class, nodes/relationships, options, callbacks, hit testing, image export
- `@neo4j-nvl/interaction-handlers` — `ZoomInteraction`, `PanInteraction`, `DragNodeInteraction`, `ClickInteraction`, `HoverInteraction`, `BoxSelectInteraction`, `LassoInteraction`, `KeyboardInteraction`
- `@neo4j-nvl/react` — `InteractiveNvlWrapper`, `BasicNvlWrapper`, `StaticPictureWrapper`
- `nvlResultTransformer` for piping `driver.executeQuery` results straight into NVL
- Canvas vs WebGL renderer selection (~1k vs 100k+ nodes)
- Layout selection (`forceDirected`, `hierarchical`, `circular`, `grid`, `free`, `d3Force`)
- Container setup, Web Worker fallback, telemetry opt-out

**Not covered** (see sibling tools / skills):
- Out-of-the-box embedded graph view with default styling → `GraphVisualization` component in `@neo4j-ndl/react` (Neo4j Needle design system) — wraps NVL with defaults
- Python / Jupyter graph visualization → `neo4j/python-graph-visualization` (Python port of NVL)
- Cypher query authoring → `neo4j-cypher-skill`
- Driver lifecycle, sessions, `executeQuery` setup → `neo4j-driver-javascript-skill`
- GDS algorithms → `neo4j-gds-skill` / `neo4j-aura-graph-analytics-skill`

**Compatibility:** `@neo4j-nvl/base` 1.1+; React 19 for `@neo4j-nvl/react`; modern browsers with Canvas2D + WebGL2.

**Install:**

```bash
npm install @neo4j-nvl/base
npm install @neo4j-nvl/interaction-handlers   # optional, for vanilla JS interactions
npm install @neo4j-nvl/react                  # optional, for React apps
```

Starter templates: https://github.com/neo4j-devtools/nvl-boilerplates

**Install skill:**

```bash
npx skills add https://github.com/neo4j-contrib/neo4j-skills
```


# NVL — API Surface Reference

Source: `@neo4j-nvl/base@1.1`, `@neo4j-nvl/interaction-handlers@1.1`, `@neo4j-nvl/react@1.1`.

## Packages

| Package | Main export | Notes |
|---|---|---|
| `@neo4j-nvl/base` | `NVL` (also default), types, `nvlResultTransformer`, layout constants | Framework-agnostic core |
| `@neo4j-nvl/interaction-handlers` | `ZoomInteraction`, `PanInteraction`, `ClickInteraction`, `HoverInteraction`, `DragNodeInteraction`, `BoxSelectInteraction`, `LassoInteraction`, `KeyboardInteraction` | Compose onto an `NVL` instance |
| `@neo4j-nvl/react` | `InteractiveNvlWrapper`, `BasicNvlWrapper`, `StaticPictureWrapper` | React 19 |
| `@neo4j-nvl/layout-workers` | (transitive) | Force-directed + hierarchical workers |

---

## `NVL` Class

### Constructor

```typescript
new NVL(
  frame: HTMLElement,
  nvlNodes?: Node[],                  // default []
  nvlRels?:  Relationship[],          // default []
  options?:  NvlOptions,              // default {}
  callbacks?: ExternalCallbacks       // default {}
)
```

### Element CRUD

| Method | Signature | Purpose |
|---|---|---|
| `addAndUpdateElementsInGraph` | `(nodes: Node[] \| PartialNode[], rels: Relationship[] \| PartialRelationship[]) => void` | Insert new; update existing by id |
| `addElementsToGraph` | `(nodes: Node[], rels: Relationship[]) => void` | Insert only |
| `updateElementsInGraph` | `(nodes: PartialNode[], rels: PartialRelationship[]) => void` | Update existing only; ignores unknown ids |
| `removeNodesWithIds` | `(ids: string[]) => void` | Remove nodes + adjacent relationships |
| `removeRelationshipsWithIds` | `(ids: string[]) => void` | Remove relationships |

### Element Read

| Method | Signature |
|---|---|
| `getNodes` | `() => Node[]` |
| `getRelationships` | `() => Relationship[]` |
| `getNodeById` | `(id: string) => Node` |
| `getRelationshipById` | `(id: string) => Relationship` |
| `getPositionById` | `(id: string) => Node` |
| `getNodesOnScreen` | `() => { nodes: Node[]; rels: Relationship[] }` |
| `getNodePositions` | `() => (Node & Point)[]` |
| `setNodePositions` | `(data: Node[], updateLayout?: boolean) => void` |
| `getSelectedNodes` | `() => (Node & Point)[]` |
| `getSelectedRelations