Skip to content

Graph (Network)

The Graph chart renders networks of relationships — entity connections, agent networks, blockchain addresses. Instead of a single force simulation, it is a viewport over a headless graph model with deterministic views: ego (who surrounds a node), path (how two nodes are connected), cluster (the shape of the whole network), and flow (a trace of value moving through ordered lanes — money trails, supply chains). You never draw the full graph — you draw the answer to a query.

Experimental. Graph is not covered by the 1.0 stability guarantee — its layout, rendering, and options may change without a major-version bump. For production reporting, prefer the stable chart types.

Ego view

Nodes snap to a regular grid sized for the neighborhood. The focused node is pinned to the center cell; every category (node group) owns a home corner or edge and fills cells from its far corner toward the center — so the deepest connections sit at the rim and first-ring ones end up next to the ego, and distance from the center still reads as degrees of separation. When one category holds almost the whole neighbourhood (over 80% of at least six nodes), it has no corners to share: it fills the grid from the ego outwards instead, first ring nearest, and the few others sit just outside it towards their corners. The layout is deterministic — same data, same picture. Nodes are monochrome with a category glyph; color belongs to the links, and the filled dark node marks the current center. Click any node to recenter on it: the chart queries the source for that node's neighborhood, and nodes present in both views travel to their new positions instead of being redrawn. Zoom out (the − button, Ctrl/⌘ + wheel or a pinch) to switch to the cluster overview (semantic zoom).

Path view

"How are A and B connected?" — up to pathCount edge-disjoint routes, laid out left to right: columns are hops, each route gets its own row with a hop-count caption, and the shortest route is visually emphasized while the alternatives recede. Each endpoint's other connections fan out behind it, faded — showing that both nodes are well connected beyond these routes (disable with pathContext: false). Pathfinding is the data source's job (server-side on a real backend), because the client only holds the neighborhoods it has walked.

Cluster view

The whole network collapsed into communities (Louvain). Meta-nodes stand on the same kind of grid as the ego view — the largest community in the centre, the rest spiralling out — so big communities never overlap. Each meta-node is labelled by its most-connected member; size encodes the community size, link width the number of real edges between groups (up to eight; more draw at full width). Click a community to dive into the ego view of its top member; zoom in to dive back to the last ego view.

Example: warm-intro routing

A CRM-style scenario: the ego view is centered on a sales rep, and target leads — deliberately not connected to the rep — are marked with a star glyph. Clicking a lead answers the question that matters: who can introduce me? The onNodeClick callback switches to the path view with the warm-intro routes; clicking the rep restores the ego view. Category glyphs (person, company, partner org, ★ lead) carry the node semantics, so all the color stays on the relationship types.

Data source

Graph reads data through a source adapter with three async queries — the same contract a real graph backend would implement:

{
  neighbors(id, { depth, types })  // → { nodes, links }         — ego view
  paths(a, b, { k })               // → { paths, nodes, links }  — path view
  aggregates()                     // → { communities, links }   — cluster view
}

Ids arrive as strings. types is an array of relation types, or null for all; the path view also asks neighbors(id, { depth: 1 }) for each endpoint's context. paths() must return paths — arrays of node ids, shortest first — with the nodes and links along them; for a node and itself (connect(a, a)) that is one route of one node, [[a]], which the path view draws alone, without routes or context. aggregates() returns communities: [{ id, label, size, top }] (top is the member a click focuses) and links: [{ source, target, weight }] between community ids, weight being the number of ties. A query that throws is logged to the console and the view stays as it was.

For static payloads, RareCharts.memorySource(data) simulates that backend over a full in-memory graph:

const dataSource = RareCharts.memorySource({ nodes, links });
new RareCharts.Graph('#chart', { dataSource, depth: 2 }).focus('some-node');

The option is named dataSource because source keeps its usual RareCharts meaning — the attribution line in the chart footer.

Everything the user walks through accumulates in a client-side model: views are laid out from it, and nodes keep their identity from one view to the next, so shared nodes travel instead of being redrawn. It is not a response cache: every focus(), connect(), overview() and back() asks the source again, with the current depth and relation filter, so a source that is slow or expensive to call should cache its own answers. Swapping memorySource for a real backend adapter changes nothing else.

Nodes

Each node requires only id. label and every other field are optional; when no label is supplied, Graph displays the id:

Field Type Default Description
id string — Unique identifier (required)
label string id Display name
group string — Node category: picks the glyph inside the node (nodeIcons), the ego sector with groupBy: 'group' (nodes without a group share an other sector) and the category line of the tooltip. Nodes stay monochrome; in the flow view nodeGroups colors nodes by group
size number 1 Radius multiplier 0.6–3; read only with sizeBy: 'field' (nodes are uniform by default)
color string — Explicit fill override. By default nodes are monochrome — color encodes link types only
image string — Avatar URL, rendered inside the circle
hidden boolean false Keep the node out of the ego view without removing it from the data — for known-but-noisy entities. Runtime equivalent: hide(id) / show(id). The path view still draws routes through hidden nodes
note string — A paragraph about the node in the built-in details panel (details: true); description is read too

Each link requires source and target node ids. from and to are read as source and target, and the ties may come as flows instead of links — every view reads both names (they are the same in Sankey and MapFlow):

Field Type Default Description
source string — Source node id (required). from is accepted as an alias
target string — Target node id (required). to is accepted as an alias
id string derived Identity of the tie. Without it, the same pair and type is one tie: loading it again updates it in place
type string 'default' Controls color, dash style, arrow, legend label — and ego sectors. One type per tie: a types: [...] array is not read; a pair with several types is several ties
weight number 0.5 0–1. Observable tie strength from your domain (deal count, transaction volume). Drives line thickness and the choice of a node's primary branch in the ego layout. strength is accepted as a legacy alias; when a link has both, weight wins
label string — Shown in the tie's tooltip, not rendered on the graph
sources array — [{ url, title }] or URL strings — evidence for the tie, listed in its tooltip and the details panel. http(s), site-root (/…) and # URLs become links (click the tie to pin it and follow them); anything else is shown as text

Several ties between one pair. A pair can carry ties of different types — family, investment and employment at once. Give each its own link, one link per type. They are drawn as parallel arcs; a pair with more than three ties collapses into one line with a +N badge, and its tooltip lists them all. Filtering a type in the legend hides only that type's arc, not the pair. The same tie listed in both directions counts once — in the drawing, the tooltip and the details panel (the flow view, where direction matters, keeps both).

Note the division of labor: link weight is data you bring (observable ties), while node importance is computed — with sizeBy: 'degree' a node's size follows how many distinct neighbors it has in everything loaded, so "who has the most connections" is an answer, not an input.

The type field on a link is resolved against the linkTypes map you pass in. Each entry defines how that type looks:

{
  professional: { color: '#1677ff', dash: null, label: 'Professional' },
  family:       { color: '#00c97a', dash: null, label: 'Family'       },
}
  • color — stroke color for the link line and arrow
  • dash — SVG stroke-dasharray string, or null for solid
  • label — text shown in the legend

A link without a type belongs to the default type. While you pass no linkTypes, the ego, path and cluster views draw it gray (#888888) and label it Connection; with a linkTypes map or a preset — and always in the flow view — it takes the theme's muted color and the label connection, unless the map describes default itself. A type that linkTypes does not describe takes a palette color by its order among the types in use — the same rule in every relation chart (Graph views, Sankey, Map Flows). The tooltip and the details panel name a tie's category the way the drawing colors it. Five presets are available via RareCharts.linkPresets:

Preset Types
personal professional, family, friendship, investment, philanthropy, education
knowledge partOf, causes, related, example, contradicts, prerequisite, extends
org subsidiary, investment, board, partnership, acquisition, competitor
tech depends, calls, dataFlow, inherits, optional
causal causes, enables, blocks, correlates, weakens

Options

Common options shared by all chart types (title, subtitle, source, note, controls, theme) are documented on the Settings page. Graph ignores margin: the drawing fills the card.

Option Type Default Description
view string 'ego' 'flow' turns on the flow view (lanes and trace options: see Flow view). Otherwise the view follows the method you call — focus() (ego), connect() (path), overview() (cluster); setData() opens an ego view
dataSource object — Source adapter (see Data source above). Optional if you call setData()
depth number 2 Ego neighborhood depth (rings)
groupBy string 'group' Ego sectors by node 'group' or by first-ring link 'type'
sectorLabels boolean false Caption the ego category corners
hiddenNodes array [] Node ids to keep out of the ego view (see the hidden node field)
relationTypes array — Initial ego-view relation filter: only the listed types are traversed and drawn — an off-type tie between two visible nodes stays hidden. Links without a type match 'default'. Omit or pass an empty array to show every relation type
legendInteractive boolean true The type legend's items are toggles. In the ego view they filter the traversal (as setRelationTypes, re-queried); in the flow view they hide and show tie categories (as setLinkTypesVisible, see Flow view). false: a static legend of the types drawn. The old name interactiveLegend is not read; a console warning says so
onLegendToggle function — ({ name, visible, visibleNames }) => void after a legend gesture has redrawn (in the ego view, after its re-query); name is null for "Show all". The methods never call it
breadcrumbs boolean true Show clickable semantic history after the user visits more than one view
historyLimit number 12 Maximum number of graph states retained by breadcrumb and back() navigation
onNodeClick string | function 'recenter' 'recenter', a ({ node, event }) => … callback, or null (also false): clicks do nothing
pathCount number 3 Max routes fetched by connect()
pathContext boolean true Fan the endpoints' other connections behind them in the path view, faded
pathContextCount number 8 Max context ties per endpoint
semanticZoom boolean true Zooming out of ego switches to the cluster view, and back
height number 520 Card height in px — title, legend, breadcrumbs and footer included; on a narrow card they wrap and take more of it, and the drawing gets what is left (see Sizing below)
nodeRadius number 22 Base node radius in px. Per-node size multiplies this
nodeIcons object | false built-in set Glyphs inside nodes by group: { group: svgPath } (24×24 viewBox), merged over built-ins for person, company, fund, org, politics, education, crypto, lead, cluster. false renders plain circles
sizeBy string — Uniform size by default. 'degree' computes size from connectivity in the accumulated model; 'field' reads the per-node size value
zoom boolean true +/−/reset buttons, drag-to-pan, Ctrl/⌘ + wheel or a trackpad pinch to zoom; on a phone two fingers pan and pinch. A plain wheel or one finger scrolls the page, with a short hint
details boolean | element | selector — A details panel inside the card. true: the library shows the hovered node or the clicked tie (in the ego view the focused node when nothing is hovered; in the flow view the selected node or tie) — name, group, connections, a node's note, a tie's value, period and sources. An element or selector: your own panel, which gets the class rc-graph-details — it styles h4, dl, ul and the .rc-graph-details-kind / .rc-graph-details-muted lines, so your content can match the built-in panel; in the flow view fill it from onSelect (the other views have no selection event). Beside the drawing when the card is at least detailsBreakpoint wide, below it otherwise; in the flow view the drawing also keeps minWidth beside the panel
detailsFormat function built-in ({ node, link, view }) => html for details: true
detailsWidth / detailsBreakpoint / detailsHeight number 300 / 1000 / 200 Side panel width; card width from which the panel sits beside the drawing; panel height when it sits below (the card grows by it)
fullscreen boolean true Full-screen button in the footer tools; Esc or the button exits. Programmatic: toggleFullscreen(on?)
maxNodes number | 'auto' 'auto' Cap on rendered ego nodes. 'auto' derives it from the canvas size (at least 12); first-ring and best-connected nodes win. Clicking +N more opens the omitted-node list, where any node can become the new focus
draggable boolean true Nodes can be hand-dragged to fine-tune the picture; positions persist until the next view change. Movement under 6 px counts as a click
linkTypes object { default: … } Type styling map or a preset (see Link types above); without it, untyped ties are gray #888888, labelled Connection
tooltipFormat function built-in ({ node, links }) => html — custom tooltip renderer
linkTooltipFormat function built-in ({ link, source, target }) => html — tooltip for a tie; source/target are the endpoint nodes
valueFormat function locale number v => string for a tie’s value in its tooltip and the details panel, as on Sankey: v => '$' + v.toLocaleString()
duration number 500 Transition ms for view changes after the first render (it does not animate); respects reduced-motion

Sizing

Graph lays nodes out on a grid: one node per cell of about 96 × 50 px (the node and its label). The drawing area therefore decides how many nodes fit — roughly floor(width / 96) × floor(height / 50) − 1 around the focused node. A larger neighbourhood is capped to the best-connected nodes; a +N more button in the footer lists the rest — pick one to recenter on it — and the full-screen button (⛶) gives the graph the whole screen, so more of it fits (see maxNodes, fullscreen).

height is the whole card — title, legend, breadcrumbs and footer included; the drawing gets what is left, typically 80–120 px less.

View Width Height Holds
Ego, cluster720 px and up520–640~35 nodes at 720 × 520, ~80 at 960 × 640; full screen on a laptop, ~150
Path640 px and up360 for 3 routes, +110 per extra route3–5 routes with endpoint context
FlowminWidth ≈ 120–170 px per lane~110 px per row in use + 160lanes scroll sideways below minWidth
  • Neighbourhood bigger than the card? Enlarge height first (width is usually fixed by the page column), then lower depth to 1, or set maxNodes to show a curated top slice.
  • Narrow screens. Below ~480 px an ego neighbourhood of more than ~15 nodes does not read; use depth: 1, a smaller maxNodes, or the flow view with minWidth and sideways scrolling.
  • Long labels are cut to the cell width with an ellipsis; the full name is in the tooltip.

Methods

Methods return the chart instance, so calls chain — except whenReady() (a promise), isCollapsed(id) (a boolean) and getView() (the current period). Fetching and rendering are async: whenReady() resolves when queued view changes are done. A query that fails is logged to the console and the promise still resolves.

const graph = new RareCharts.Graph('#chart', { dataSource, depth: 2 });

graph.focus('peter-thiel');              // ego view around a node
graph.focus('peter-thiel', {
  types: ['investment', 'professional'], // filter the neighbors() query
});
graph.connect('peter-thiel', 'target');  // routes between two nodes
graph.overview();                        // community overview
graph.setData({ nodes, links });         // static payload: memorySource + focus on the best-connected node
graph.setData({ nodes, links }).focus('peter-thiel');
                                         // start elsewhere: chain it, no whenReady() in between
graph.add({ links: [{ source: 'a', target: 'b', type: 'deal' }] });
                                         // incremental: merge one news-sized payload
graph.hide('noisy-node');                // declutter; show(id) brings it back
graph.setRelationTypes(['investment']);  // update the current ego filter
graph.clearRelationTypes();              // restore all relation types
graph.back();                            // previous ego/path/cluster state
graph.clearHistory();                    // keep only the current breadcrumb
graph.toggleFullscreen();                // full screen on/off (also the ⛶ button, Esc)
await graph.whenReady();

await at the top level needs a <script type="module"> or an async function; in a classic <script> write graph.whenReady().then(() => …).

setData() replaces the data and starts over: the breadcrumbs and back() begin with its first view, and the legend lists the relation types of the new data only (under relationTypes, the linkTypes catalogue). Unless a view method follows in the same tick, it focuses the node with the most distinct neighbours — counted over the ties the view draws, so under relationTypes over those types; from / to count as source / target, a tie to itself or without both ends does not count. A payload with no nodes and no ties clears the drawing, its legend and notes; a single node without ties is focused and drawn alone.

The flow view adds setFilter, setTimeWindow, select / clearSelection, setLinkLabels, setHulls, the fold methods (collapse, expand, isCollapsed, setFolds) and time navigation (setTimeframe, setView, getView, onViewChange) — see the Methods section of Flow view.

add() is built for feed-driven graphs (a news item asserts a new tie): the minimal payload is a single link — endpoint nodes are created automatically, with the label falling back to the id. It refreshes an ego view. Path and cluster views draw what the source answers, so there the new tie appears with the next ego view (focus()); the flow view takes new data through setData().

A news feed

A feed-driven graph starts with the one node the story is about — a one-node payload focuses it and draws it alone — and grows by one add() per event. The ego view around that node refreshes with each tie. A tie's type is the kind of event (a deal, a sanction, an incident), drawn by your own linkTypes:

const graph = new RareCharts.Graph('#chart', {
  linkTypes: {
    deal:     { color: '#1677ff', label: 'Deal' },
    sanction: { color: '#cf1322', label: 'Sanction' },
  },
}).setData({ nodes: [{ id: 'acme', label: 'Acme Corp' }], links: [] });

// one tie per news item; a new counterpart node is created from its id
feed.on('item', item => graph.add({
  links: [{ source: 'acme', target: item.party, type: item.kind, label: item.headline }],
}));

Interaction

Recenter on click — clicking a node fetches its neighborhood and re-lays the view around it; shared nodes animate to their new positions so you keep your bearings while walking the graph. In the cluster view, clicking a community recenters on its most-connected member.

Focus + context on hover — hovering a node highlights its direct neighborhood and fades everything else, along with a tooltip listing connections by type.

Keyboard — the nodes share one Tab stop: the focused node in the ego view, the first endpoint in the path view, otherwise the node focused last. ← and → step through the nodes row by row, so every node can be reached; ↑ and ↓ go to the nearest node above or below, Home and End to the first and last. A focused node shows what hover shows — the tooltip, the highlight and the details panel. Enter or Space acts as a click (onNodeClick), Escape hides the tooltip and the highlight. Each node is announced by its label, group and number of connections.

The ties have one Tab stop of their own, after the nodes: the tie focused last, else the first. The arrows step through the ties, Home and End go to the first and last, and focus shows what hover shows — the tooltip and the highlight. Enter or Space pins the tooltip, as a click does; Tab then goes into it, to its sources links, and Shift+Tab comes back to the tie. Tab past the last link, or Escape, releases the tooltip and returns to the tie. Ties are announced as "from → to, type, label"; a pair drawn as one line with a +N badge, as "from → to, N ties".

The drawing is a group named by ariaLabel, else from title / subtitle, whose nodes and ties are buttons (a node is an image when onNodeClick is null).

Ties: hover and pin — hovering a tie highlights it and its two endpoints and shows its tooltip: endpoints, type, label, value, period and sources. Clicking a tie pins the tooltip, so links inside it can be followed; a click elsewhere or Escape releases it.

Filter relations from the legend — a click (or Enter / Space) turns a relation type off or on; a double click keeps only that type, a second one brings all back; "Show all" shows while a type is off. In the ego view this filters the traversal: it is applied to the neighbors() query and the client-side neighborhood, and with every type off the view is the focused node alone. The flow view's legend sets visibility instead (setLinkTypesVisible). Graphs whose links have no explicit type continue to work as a single default relation type.

Reveal omitted nodes — when the viewport cap removes nodes from the drawing, a +N more button appears in the footer tools; it opens an accessible list. Or open the graph full screen (⛶) — the bigger canvas fits more. Selecting an item recenters the graph on it. Capacity omissions are separate from nodes hidden explicitly with hide().

Breadcrumb navigation — after more than one semantic view has been visited, Graph shows a clickable history of ego, path, and cluster states. Returning through a breadcrumb or back() restores the relation filter together with the view; literal pan and zoom are deliberately reset.

Footer tools — +/− zoom, ⟲ resets, dragging the background pans, Ctrl/⌘ + wheel or a pinch zooms (a plain wheel stays with page scrolling). ⛶ opens the graph full screen; Esc or ✕ closes it. When nodes did not fit, +N more lists them; N hidden · restore brings back nodes hidden with a right-click. The buttons carry the class rc-graph-tool, a hook for page CSS, and the +N more list is drawn like the tooltip. The tools, the lists, the details panel and full screen follow the chart's theme: with darkTheme they are dark too.

Node dragging — drag any node to fine-tune the picture (no simulation fights back); hand-placed positions survive re-renders until the next view change. A click with a slight tremor (under 6 px) stays a click.

Hide on right-click — right-click any node in the ego view to hide it (the focused center is exempt); an "N hidden · restore" button in the footer tools brings everything back. Same mechanism as the hidden field and hide(id)/show(id) — the node stays in the model and in path routes.

Semantic zoom — zooming far out of an ego view switches to the cluster overview; zooming into the overview returns to the last ego view. Disable with semanticZoom: false.

Minimal example

new RareCharts.Graph('#chart', {
  linkTypes: RareCharts.linkPresets.personal,
  depth: 2,
}).setData({ nodes, links });

Notes

The demos on this page run on a ~300-node synthetic network around Peter Thiel (generated deterministically — a stand-in for a graph database). The layouts are deterministic by design: grid cells, category corners and route maps encode what is known about the data instead of asking a physics simulation to discover it. If a view still looks busy, reduce depth, filter link types, or let the cluster view do the summarizing.