Build Graphs from Data

Convert business data into graph visualizations using the GraphBuilder API.

Before Building

Always query the yFiles MCP for current API:

yfiles:yfiles_get_symbol_details(name="GraphBuilder")
yfiles:yfiles_search_documentation(query="GraphBuilder tutorial")

Quick Start

import { GraphBuilder } from '@yfiles/yfiles'

const builder = new GraphBuilder(graph)
builder.createNodesSource({ data: nodesData, id: 'id' })
builder.createEdgesSource({
  data: edgesData,
  id: 'id',
  sourceId: 'source',
  targetId: 'target'
})
builder.buildGraph()

Key Concepts

• Data stays in tags: Original data objects are stored in element.tag after build
• ID mapping: Use field name strings or accessor functions for id, sourceId, targetId
• Build order: Groups → nodes → edges (groups must exist before their children)
• Provider functions: Compute styles, labels, and layouts from data at build time
• updateGraph(): Incrementally updates an existing graph instead of rebuilding from scratch

Important: Never directly assign to readonly properties like node.layout, edge.sourceNode, or edge.targetNode. Use IGraph methods instead (e.g., graph.setNodeLayout(), graph.setEdgePorts()). The @yfiles/eslint-plugin rule @yfiles/suggest-setter-methods warns about these mistakes.

After Building

Apply a layout to position the nodes:

/yfiles-layout

Additional Resources

• references/patterns.md — Node/edge creation, custom styles from data, labels, node positioning, updating graphs
• references/advanced.md — Group nodes, ports and bends, TreeBuilder, AdjacencyGraphBuilder
• references/examples.md — Complete working code examples