Graphiti — Visual Graph Editor & Rules Engine

Inspector

Click a node or edge to inspect

Rules

Rules Reference

Syntax

One rule per line. Lines starting with # or // are comments.

NODES.property: expression
EDGES.property: expression
CONNECT: expression
ANIM.varname: min..max
CRAWL[N].property: expression

Node Visual Properties

Set appearance per node. The expression receives node (metadata), _node (full object), and graph (helpers).

# Color by a metadata field
NODES.color: node.type

# Conditional color
NODES.color: node.age > 50 ? "red" : "blue"

# Size by connection count
NODES.size: graph.degree(_node)

# Custom label
NODES.label: `${node.name} (${node.type})`

# Transparency
NODES.opacity: node.active ? 1 : 0.3

# Shape
NODES.shape: node.kind

# Position — center-point (locks in place, disables drag)
NODES.x: node.col * 200
NODES.y: node.row * 80

# Position — edge-based (left/top of bounding box)
NODES.left: node.start_date * 100
NODES.top: node.priority * 80

# Dimensions (independent width/height in pixels)
NODES.width: node.duration * 50
NODES.height: 40

Properties: color, size, label, description, opacity, shape, x, y, left, top, width, height

Colors can be hex strings ("#ff0000"), or any value — strings and numbers are auto-mapped to distinct colors.

x/y set the node's center point. left/top set the upper-left corner (auto-converted using width/height). If both are set, left/top win. Any position property locks the node in place — no dragging, pinned during force layout.

Dimensions (width/height) override the default 140×50 box. If size is set without explicit width/height, it scales both proportionally.

Edge Visual Properties

Set appearance per edge. The expression receives edge (metadata), from/to (endpoint metadata), _edge/_from/_to (full objects), and graph.

# Color edges by source type
EDGES.color: from.type

# Width by weight
EDGES.width: edge.weight

# Label
EDGES.label: edge.relationship

# Transparency
EDGES.opacity: edge.confidence

# Physics spring strength (0–1, default 0.4)
EDGES.spring: edge.weight / 10

Properties: color, width, label, opacity, spring

Filtering (Visibility)

Hide nodes or edges that don't match. Multiple visible rules are AND-ed — all must be true.

# Only show people
NODES.visible: node.type === "Person"

# Only show high-weight edges
EDGES.visible: edge.weight > 5

# Combine filters (both must pass)
NODES.visible: node.type === "Person"
NODES.visible: node.age > 30

Grouping

Collapse nodes that return the same value into a single group node. Groups with only 1 member are not collapsed. First NODES.group rule wins.

# Group by type
NODES.group: node.type

# Group by computed bucket
NODES.group: node.age > 40 ? "senior" : "junior"

Group nodes expose metadata: _groupKey, _memberCount, _memberIds. Edges between groups are collapsed with a _count.

Group Aggregation

Compute metadata on group nodes/edges with NODES.group.<key>: / EDGES.group.<key>: rules. Expressions receive nodes or edges (member metadata arrays) and helpers: sum, avg, min, max.

# Aggregate member volumes onto group nodes
NODES.group.total_volume: sum(nodes.map(n => n.volume_mbd))
NODES.group.avg_volume: avg(nodes.map(n => n.volume_mbd))
NODES.group.big_exporters: nodes.filter(n => n.volume_mbd > 3).length

# Aggregate edge flows
EDGES.group.total_flow: sum(edges.map(e => e.volume_mbd))

# Use aggregated values in visual rules
NODES.size: node.total_volume * 3
EDGES.width: edge.total_flow * 2

Programmatic Edges (CONNECT)

Create edges between every node pair where the expression is true. Receives from/to (metadata), _from/_to (full objects), and graph.

# Link nodes that share an attribute
CONNECT: from.department === to.department

# Link assignees to their tasks
CONNECT: from.assignee === to.email

# Use optional chaining for sparse data
CONNECT: from.tags?.includes(to.name)

Edges where both sides of a comparison are undefined are suppressed (prevents false matches on missing fields).

Use Bake Selected / Bake All to convert programmatic edges into permanent manual edges.

Animation Variables (ANIM)

Declare scrub-able variables that can be used in any expression. A slider bar appears below the toolbar when ANIM rules are present.

# Numeric range
ANIM.threshold: 0..100

# With step size
ANIM.t: 0..1 step 0.01

# Date range (ISO format)
ANIM.cutoff: 2020-01-01..2025-12-31

Use the variable in expressions via _anim.varname:

# Filter nodes by animated threshold
NODES.visible: node.score > _anim.threshold

# Animate position over time
NODES.left: _anim.t * 800

# Date filtering with date() helper
NODES.visible: date(node.created) < _anim.cutoff

The date() helper converts strings or values to epoch milliseconds. Available in all expressions.

date("2024-01-15")    # parse ISO string → ms
date(node.timestamp)  # convert value → ms
date()                # current time (Date.now())

Graph Helpers

The graph object provides structural queries. Pass _node, _from, or _to (the full node objects).

graph.degree(_node)        # total edges
graph.inDegree(_node)      # incoming edges
graph.outDegree(_node)     # outgoing edges
graph.neighbors(_node)     # [{metadata}, ...]
graph.inbound(_node)       # [{metadata}, ...]
graph.outbound(_node)      # [{metadata}, ...]
graph.edges(_node)         # [{metadata}, ...]
graph.nodes                # all node metadata
graph.min("field")         # min value across all nodes
graph.max("field")         # max value across all nodes
graph.scale("field")          # normalize to 0..1
graph.scale("field", lo, hi)  # normalize to lo..hi

Normalizing Numeric Data

graph.scale() maps a field to a range across the whole graph — ideal for size, width, opacity:

# Node size from 0.5× to 3× based on weight
NODES.size: graph.scale("weight", 0.5, 3)

# Edge width 1..8 based on flow
EDGES.width: graph.scale(_from, "flow", 1, 8)

Or compose the primitives for full control:

# Equivalent longhand
lerp(norm(node.weight, graph.min("weight"),
          graph.max("weight")), 0.5, 3)

# Explicit node form (also works)
NODES.size: graph.scale(_node, "weight", 0.5, 3)

Built-in Functions

when(cond, value)    # returns value if cond is truthy, undefined otherwise
no(value)            # true if value is null or undefined
date(value)          # convert to days since epoch (for date arithmetic)
norm(val, min, max)  # normalize to 0..1, clamped
lerp(t, a, b)        # linear interpolation: a + t*(b-a)
clamp(val, lo, hi)   # clamp to [lo, hi]

when() is useful for applying rules to a subset of nodes/edges. Because undefined results don’t overwrite earlier rules, multiple when() rules for the same property compose cleanly:

# Color countries by volume, chokepoints by throughput
NODES.color: when(node.type === "country", node.volume_mbd)
NODES.color: when(node.type === "chokepoint", node.throughput_mbd)

Context Variables

Context	Variables
Node rules	`node` `_node` `graph` `_anim` `date()`
Edge rules	`edge` `from` `to` `_edge` `_from` `_to` `graph` `_anim` `date()`
CONNECT	`from` `to` `_from` `_to` `graph` `_anim` `date()`
ANIM	min..max range definition (not an expression)

Shorthand variables (node, edge, from, to) expose metadata directly. Underscore-prefixed versions (_node, _edge, etc.) are the full objects with id, x, y, etc.

Tips

Expressions are JavaScript — use ternaries, template literals, optional chaining, etc.
Expressions are read-only — accidental assignment (= instead of ===) throws an error instead of mutating your data.
Rules apply top to bottom. Later rules for the same property overwrite earlier ones.
A syntax error in one rule won't break others.

Crawlers (CRAWL[N])

Animated tokens that follow paths through the graph. Each crawler is an indexed group (CRAWL[0], CRAWL[1], ...) with its own path and style. Unindexed CRAWL.* sets defaults inherited by all crawlers.

ANIM.t: 0..1 step 0.01
CRAWL.t: _anim.t
CRAWL.color: "#ff6600"

# Crawler 0: appears at segment 2
CRAWL[0].path: [1, 34, 35, 18]
CRAWL[0].visible: [0, 0, 1, 1]

# Crawler 1: different route, blue
CRAWL[1].path: [2, 34, 37, 36]
CRAWL[1].color: "#0066ff"
CRAWL[1].sizes: [10, 8, 6, 4]

Property	Scope	Default	Description
`path`	CRAWL[N]	—	Node ID sequence `[A, B, C, ...]`
`visible`	CRAWL[N]	all visible	Per-segment visibility `[0\|1, ...]`
`sizes`	CRAWL[N]	—	Per-segment radius `[num, ...]`
`color`	both	`"#ff6600"`	Circle fill color
`size`	both	`5`	Base circle radius in px
`t`	both	`_anim.t`	Position along path, 0..1

CRAWL[N].* overrides CRAWL.* defaults for that crawler. path, visible, and sizes are per-crawler only.