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 |
Links
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.
Link types
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 arrowdash— SVGstroke-dasharraystring, ornullfor solidlabel— 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, cluster | 720 px and up | 520–640 | ~35 nodes at 720 × 520, ~80 at 960 × 640; full screen on a laptop, ~150 |
| Path | 640 px and up | 360 for 3 routes, +110 per extra route | 3–5 routes with endpoint context |
| Flow | minWidth ≈ 120–170 px per lane | ~110 px per row in use + 160 | lanes scroll sideways below minWidth |
- Neighbourhood bigger than the card? Enlarge
heightfirst (width is usually fixed by the page column), then lowerdepthto 1, or setmaxNodesto 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 smallermaxNodes, or the flow view withminWidthand 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.